Создание реестров

Статья
01/10/2024

Сведения об использовании реестров см. в разделе "Использование реестров".

Обзор

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

Реестры Git — это простые репозитории git и могут быть общедоступными или закрытыми через обычные механизмы для репозиториев Git. Например, репозиторий vcpkg является реестром Git.

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

Мы ожидаем, что набор типов реестра будет расти с течением времени; Если вы хотите поддержать реестры, встроенные в любимую общедоступную систему управления версиями, не стесняйтесь открывать pr.

Базовая структура реестра:

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

Реестры Git

По мере выполнения этой документации может быть полезно использовать рабочий пример для ссылки. Мы написали один и положили его здесь:

Microsoft/vcpkg-docs: реестр vcpkg.

Все реестры Git должны иметь versions/baseline.json файл. Этот файл содержит набор "последних версий" в определенной фиксации. Он размещается как объект верхнего уровня, содержащий только "default" поле. Это поле должно содержать имена портов сопоставления объектов с версией, которая в настоящее время является последней.

Ниже приведен пример допустимого baseline.json:

{
  "default": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  }
}

В versions каталоге содержатся все сведения о версиях пакетов, содержащихся в реестре, а также о том, где хранятся эти версии. Остальная часть реестра просто выступает в качестве резервного хранилища, что касается vcpkg: только вещи внутри versions каталога будут использоваться для управления тем, как ваш реестр видится vcpkg.

Каждый порт в реестре должен существовать в каталоге версий, так как <first letter of port>-/<name of port>.json, другими словами, сведения о kitten порту будут находиться в versions/k-/kitten.json. Это должен быть объект верхнего уровня только с одним полем: "versions" Это поле должно содержать массив объектов версии:

Версия порта, о который идет речь; должен совпадать с vcpkg.json файлом, включая поля версии и "port-version".
Поле "git-tree" , которое является деревом git; другими словами, то, что вы получаете при записи git rev-parse COMMIT-ID:path/to/port.

Поле версии для портов с устаревшими CONTROL файлами "version-string".

Предупреждение

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

Ниже приведен пример допустимой базы данных версий для kitten порта с одной версией:

{
  "versions": [
    {
      "version": "2.6.2",
      "port-version": 0,
      "git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e"
    }
  ]
}

Как правило, не важно размещать каталоги портов. Тем не менее, идиом в vcpkg заключается в том, чтобы следовать тому, что делает встроенный реестр vcpkg: kitten ваш порт должен быть помещен в ports/kitten.

Предупреждение

Имейте в виду, что при обновлении реестра все предыдущие версии также должны быть доступны. Так как ваш пользователь установит базовые показатели на ИД фиксации, это ИД фиксации всегда должно существовать и быть доступным из фиксации HEAD, что на самом деле извлекается. Это означает, что фиксация HEAD должна быть дочерним элементом всех предыдущих фиксаций HEAD.

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

Встроенные реестры рассматриваются как специальные реестры Git. Вместо получения из удаленного URL-адреса встроенные реестры обращаются к $VCPKG_ROOT/.git каталогу клона vcpkg. Они используют в настоящее время извлеченный $VCPKG_ROOT/versions каталог в качестве источника сведений о версиях.

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

Существует некоторые трюки Git, связанные с созданием новой версии порта. Первое, что нужно сделать, — внести некоторые изменения, обновить "port-version" поле и регулярное поле версии по мере необходимости, а затем протестировать с помощью overlay-ports:

vcpkg install kitten --overlay-ports=ports/kitten.

Завершив тестирование, необходимо убедиться, что каталог находится под purview Git. Для этого создайте временную фиксацию:

> git add ports/kitten
> git commit -m 'temporary commit'

Затем получите идентификатор дерева Git каталога:

> git rev-parse HEAD:ports/kitten
73ad3c823ef701c37421b450a34271d6beaf7b07

Затем эту версию можно добавить в базу данных версий. В верхней части versions/k-/kitten.jsonможно добавить (при условии, что вы добавляете версию 2.6.3#0):

{
  "versions": [
    {
      "version": "2.6.3",
      "port-version": 0,
      "git-tree": "73ad3c823ef701c37421b450a34271d6beaf7b07"
    },
    {
      "version": "2.6.2",
      "port-version": 0,
      "git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e"
    }
  ]
}

Затем вы хотите изменить versions/baseline.json новую версию, а также:

{
  "default": {
    "kitten": {
      "baseline": "2.6.3",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  }
}

и измените текущую фиксацию:

> git commit --amend

а затем поделитесь!

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

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

Все реестры файловой versions/baseline.json системы должны иметь файл. Этот файл содержит набор "последних версий" для определенной версии реестра. Он размещается как объект верхнего уровня, содержащий карту от имени версии до "базовых объектов", которые сопоставляют имена портов с версией, которая считается "последней" для этой версии реестра.

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

Предупреждение

Базовые показатели не должны быть изменены после публикации. Если вы хотите изменить или обновить версии, необходимо создать новую базовую базу в baseline.json файле.

Ниже приведен пример допустимого baseline.jsonреестра, который решил даты их версий:

{
  "2021-04-16": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  },
  "2021-04-15": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 1
    }
  }
}

Версия порта, о который идет речь; должен совпадать с vcpkg.json файлом, включая поля версии и "port-version".
"path" Поле: относительный каталог, корень которого находится в базе реестра (иными словами, каталог, где versions находится), в каталог портов. Это должно выглядеть примерно так:"$/path/to/port/dir

Поле версии для портов с устаревшими CONTROL файлами "version-string".

Как правило, не важно размещать каталоги портов. Тем не менее, идиом в vcpkg заключается в том, чтобы несколько внимательно следовать тому, что делает встроенный реестр vcpkg: ваш kitten порт в версии x.y.z должен быть помещен ports/kitten/x.y.zв , с версиями портов, добавленными как вы видите (хотя так как # не хороший символ для использования для имен файлов, возможно, используйте _).

Предупреждение

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

Ниже приведен пример допустимой базы данных версий для kitten порта с одной версией:

{
  "versions": [
    {
      "version": "2.6.2",
      "port-version": 0,
      "path": "$/ports/kitten/2.6.2_0"
    }
  ]
}

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

В отличие от реестров Git, добавление новой версии в реестр файловой системы в основном включает много копирования. Первое, что нужно сделать, — скопировать последнюю версию порта в новый каталог версий, обновить версию и "port-version" поля по мере необходимости, а затем протестировать с помощью overlay-ports:

vcpkg install kitten --overlay-ports=ports/kitten/new-version.

Завершив тестирование, вы можете добавить эту новую версию в верхнюю часть:versions/k-/kitten.json

{
  "versions": [
    {
      "version": "2.6.3",
      "port-version": 0,
      "path": "$/ports/kitten/2.6.3_0"
    },
    {
      "version": "2.6.2",
      "port-version": 0,
      "path": "$/ports/kitten/2.6.2_0"
    }
  ]
}

Затем необходимо изменить versions/baseline.json новую версию (не изменяйте существующие базовые показатели):

{
  "2021-04-17": {
    "kitten": {
      "baseline": "2.6.3",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  },
  "2021-04-16": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  },
  "2021-04-15": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 1
    }
  }
}

Готово!

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

Создание реестров

Обзор

Реестры Git

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

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

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

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

Дополнительные ресурсы