Udostępnij za pośrednictwem

Pojęcia dotyczące rejestrów

  • Artykuł

Przegląd

Narzędzie vcpkg hostuje wybór bibliotek, które są pakowane w porty w https://github.com/Microsoft/vcpkg. Ta kolekcja portów jest nazywana wyselekcjonowanym rejestrem. Jednak narzędzie vcpkg nie jest ograniczone do wyselekcjonowanego rejestru. Użytkownicy mogą rozszerzyć wybór portów, tworząc niestandardowe rejestry.

Rejestr jest kolekcją portów i plików pomocnika rozmieszczonych w określonej strukturze. Postępując zgodnie ze strukturą rejestru, porty zawarte w rejestrze mogą być instalowane z tymi samymi funkcjami (wersjonowanie, keszowanie binarne), jakie są oferowane portom w nadzorowanym rejestrze.

Obecnie istnieją trzy rodzaje rejestrów:

  • Rejestr wbudowany ,
  • Rejestry Git, i
  • rejestry systemu plików .

Narzędzie vcpkg można poinstruować o rozważenie portów dostępnych w niestandardowych rejestrach przy użyciu pliku vcpkg-configuration.json. Zobacz artykuł Tutorial: Instalowanie zależności z rejestru opartego na usłudze Git, aby dowiedzieć się, jak używać niestandardowych rejestrów w swoich projektach.

Struktura rejestru

Aby program vcpkg mógł być interfejsem z rejestrem, musi być zgodny z następującą strukturą:

  • Katalog o nazwie ports zawiera kolekcję portów z każdym podkatalogem zawierającym określony port pasujący do nazwy podkatalogu. Na przykład pliki dla portu foo znajdują się w ports/foo.
  • Katalog o nazwie versions zawiera pliki stanowiące bazę danych wersji .

Przykład: struktura rejestru

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

Baza danych wersji

Wszystkie rejestry zawierają w katalogu głównym katalog versions, w którym znajduje się baza danych wersji .

Istnieją dwa składniki bazy danych wersji:

  • Plik bazowy
  • Pliki wersji

Plik odniesienia jest plikiem JSON o nazwie baseline.json znajdującym się w katalogu głównym versions.

Pliki wersji to pliki JSON o takich samych nazwach jak dostępne porty. Muszą istnieć w versions/<prefix>/<port name>.json, gdzie <prefix> jest pierwszą literą nazwy portu, po której następuje łącznik. Na przykład plik z wersjami dla portu foo musi być w versions/f-/foo.json.

Celem pliku wersji jest pełnić dwie funkcje:

  • Wyświetl listę wszystkich dostępnych wersji każdego portu
  • Wskaż lokalizacje pobierania każdej wersji.

Format pliku wersji zależy od rodzaju rejestru.

Plik bazowy

Wszystkie rejestry, niezależnie od ich rodzaju, muszą zawierać plik o nazwie baseline.json znajdujący się w versions/baseline.json.

Celem pliku odniesienia jest opisanie zestawu wersji, które są uważane za najnowsze dla wszystkich portów w rejestrze. Oczekuje się, że ten plik jest aktualizowany za każdym razem, gdy do rejestru zostanie dodana nowa wersja portu.

Plik jest plikiem JSON składającym się z pojedynczego obiektu, którego właściwości są nazwane obiektami odniesienia. Właściwości każdego obiektu bazowego to nazwy portów, których wartości stanowią wpisy wersji. W artykule dotyczącym rejestrów opisano bardziej szczegółowo układ plików punktu odniesienia.

Każdy wpis wersji punktu odniesienia jest obiektem o następujących właściwościach:

  • baseline: wartość odpowiada wersji portu zgodnej z odpowiednim plikiem vcpkg.json.
  • port-version: wartość to port-version portu zgodna z jego odpowiadającym plikiem vcpkg.json.

Przykładowy plik odniesienia

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

Zapoznaj się z dokumentacją referencyjną:

  • Układ podstawowego pliku dla rejestrów Git
  • Układ bazowy pliku dla rejestrów systemu plików

Pliki wersji

Każdy port w rejestrze ma odpowiedni plik wersji. Pliki wersji są przechowywane w versions/<prefix>/<port name>.json , gdzie <prefix> jest pierwszą literą nazwy portu, po której następuje łącznik. Na przykład plik wersji dla portu foo znajduje się w versions/f-/foo.json.

Celem pliku wersji jest podwójny:

  • Wyświetl listę wszystkich dostępnych wersji każdego portu
  • Wskaż lokalizacje pobierania każdej z tych wersji

Układ pliku wersji jest obiektem zawierającym tablicę "versions", a każdy wpis w tej tablicy jest obiektem wersji. Obiekt wersji musi zawierać następujące właściwości:

  • Właściwość wersji: klucz i wartość właściwości muszą być zgodne z wartościami używanymi przez port w pliku vcpkg.json. Klucz musi być jednym z version, version-semver, version-datelub version-string; wartość musi być wersją wyświetlaną w pliku manifestu portu (vcpkg.json).
  • port-version: wartość jest port-version portu, jak jest wyświetlana w pliku vcpkg.json portu.
  • git-tree: (tylko w rejestrach Git) wartość to SHA drzewa git odpowiadająca katalogowi portu. Jest to skrót SHA obliczany przez zhaszowanie zawartości katalogu portu; ten skrót SHA drzewa git może być używany przez Git do pobierania zawartości portu odpowiadającej podanemu drzewu git. Dzięki temu program vcpkg może pobrać stare wersje portów z historii rejestrów usługi Git. Przeczytaj sekcję rejestrów git, aby dowiedzieć się, jak uzyskać tę wartość dla danej wersji portu.
  • path: (tylko w rejestrach systemu plików) wartość jest pełną ścieżką do katalogu zawierającego pliki portów dla określonej wersji.

Przykład pliku wersji rejestru systemu plików

{
  "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
    }
  ]
}

Zapoznaj się z dokumentacją referencyjną:

  • Wersje układu plików dla rejestrów Git
  • Wersje układu plików dla rejestrów systemu plików

Rejestr wbudowany

Wbudowany rejestr jest specjalnym rodzajem rejestru. Jest to rejestr domyślny używany w trybie klasycznym . W trybie manifestu , gdy domyślny rejestr nie jest określony, vcpkg niejawnie używa wbudowanego rejestru.

Wbudowany rejestr odwołuje się do lokalnej kopii nadzorowanego rejestru utworzonego podczas git clone repozytorium vcpkg z https://github.com/Microsoft/vcpkg. Niektóre operacje oczekują, że zmienna środowiskowa VCPKG_ROOT wskazuje wbudowany rejestr.

Jeśli narzędzie vcpkg zostanie nabyte za pośrednictwem "jednego wiersza" lub instalatora programu Visual Studio, wbudowany rejestr staje się odpowiednikiem rejestru Git wskazującym repozytorium https://github.com/Microsoft/vcpkg.

Rejestry usługi Git

Rejestr Git to repozytorium, które jest zgodne ze strukturą rejestru i wykorzystuje możliwości usługi Git w celu zapewnienia przechowywania wersji portów w rejestrze. Nadzorowany rejestr w https://github.com/Microsoft/vcpkg jest implementacją rejestru Git.

Rejestry git mogą być hostowane u dowolnego dostawcy repozytorium Git, co umożliwia korzystanie z wybranej usługi hostingu Git w celu kontrolowania dostępu do rejestru niestandardowego, a także ułatwia udostępnianie rejestru.

Rejestry git to zalecana metoda implementowania rejestru niestandardowego. Ponieważ mechanizm przechowywania wersji jest taki sam, jak w przypadku nadzorowanego rejestru, rejestry git mogą korzystać z x-add-version do zarządzania plikami bazy danych wersji.

Aby uzyskać szczegółowe informacje o implementacji rejestrów Git, zobacz odniesienia do rejestrów .

Dodawanie nowej wersji do rejestru Git

Polecenie x-add-version może służyć do dodawania nowego portu lub nowej wersji do rejestru. Podczas dodawania wersji przy użyciu tego polecenia należy pamiętać o kilku kwestiach:

Ważny

Podczas dodawania nowej wersji należy zawsze pamiętać, aby zaktualizować zadeklarowaną wersję portu do wersji, która nie została jeszcze opublikowana, aby uniknąć ponownego zapisywania historii wersji.

W przypadku wprowadzania zmian w porcie pierwszym krokiem powinno być zwiększenie jego wersji w pliku vcpkg.json. Jeśli zmiany obejmują aktualizację wersji nadrzędnej pakietu , pamiętaj, aby ustawić port-version na 0; w przeciwnym razie pamiętaj, aby zwiększyć port-version o jeden.

Polecenie x-add-version wymaga zatwierdzenia wszystkich zmian portów w repozytorium przed zaktualizowaniem bazy danych wersji.

Przykład: dodawanie nowej wersji portu do rejestru 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

Opcje przekierowania --x-builtin-ports-root i --x-builtin-registry-versions-dir powinny wskazywać odpowiednio katalogi ports i versions rejestru.

Po pomyślnym uruchomieniu polecenia x-add-version zmień ostatnie zatwierdzenie, aby uwzględnić zmiany w plikach wersji.

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

Rejestry systemu plików

Rejestry systemu plików to implementacja rejestru, który znajduje się w systemie plików. Są one zgodne ze wspólną strukturą rejestru, ale nie korzystają z usługi Git w celu oferowania możliwości przechowywania wersji. Zamiast tego używają pierwotnej formy kontroli wersji przy użyciu odrębnej ścieżki dla każdej wersji portów.

Ten rodzaj rejestru nadaje się do pełnienia roli poligonu testowego dla portów lub oferowania alternatywy dla rejestru w systemach kontroli wersji innych niż Git. Rejestry systemu plików nie są zalecane w przypadku dużej kolekcji portów, a żadne narzędzia nie są udostępniane do manipulowania plikami bazy danych wersji dla tego rodzaju rejestru.

Aby uzyskać szczegółowe informacje na temat implementowania rejestru systemu plików, zobacz dokumentację rejestrów .

Korzystanie z rejestrów

Aby korzystać z rejestru niestandardowego w projekcie, należy utworzyć plik konfiguracji (vcpkg-configuration.json) obok pliku manifestu projektu (vcpkg.json).

Rejestr domyślny

W przypadku rozpoznawania nazw portów, domyślny rejestr pełni funkcję zabezpieczenia, gdy nazwa portu nie pasuje do żadnego z wzorców pakietów zadeklarowanych przez inne rejestry w tablicy registries.

Jako wygoda dla użytkowników, którzy nie angażują się w niestandardowe rejestry, vcpkg niejawnie dodaje wbudowane rejestru jako rejestru domyślnego. Aby zmienić to zachowanie, domyślny rejestr można ustawić na dowolny rejestr lub całkowicie wyłączyć, korzystając z odpowiednich ustawień. default-registry właściwość.

Przykład: ustawianie rejestru niestandardowego jako domyślnego

vcpkg-configuration.json

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

Przykład: wyłączanie rejestru domyślnego

vcpkg-configuration.json

{
  "default-registry": null
}

Tablica rejestrów

Aby rozszerzyć wybór dostępnych portów do zainstalowania za pomocą narzędzia vcpkg, można określić dodatkowe rejestry przy użyciu tablicy registries.

Przykład: dodawanie rejestrów niestandardowych do konfiguracji

Notatka

W zależności od rodzaju rejestru może być konieczne podanie różnych informacji w tablicy registries. Zapoznaj się z dokumentacją vcpkg-configurtion.json, aby dowiedzieć się, które właściwości są wymagane dla każdego rodzaju rejestru.

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" ]
    }
  ]
}

Nie zapisujej ponownie historii wersji

Po opublikowaniu wersji w plikach wersji nie należy zmieniać skojarzonego z nią git-tree w repozytorium Git ani w katalogu systemu plików.

Jedną z zasad projektowania programu vcpkg jest to, że wersje zainstalowanych zależności nie zmieniają się bez interwencji użytkownika. Ponowne zapisywanie historii plików wersji przez zmianę wpisu git-tree narusza tę zasadę.

Jeśli istniejąca wersja ma problemy, wolisz utworzyć nowy port-version.

Nie usuwaj plików wersji

Notatka

Ta sekcja dotyczy tylko rejestrów Git

Podczas usuwania portu z rejestru usuń jego zawartość z katalogu portów i jego wpis w pliku odniesienia. Ale nie usuwaj skojarzonego pliku wersji.

Nawet jeśli port nie istnieje już w rejestrze, o ile plik wersji pozostanie, użytkownicy portu mogą zainstalować stare wersje przy użyciu wersji overrides.

Następne kroki

Poniżej przedstawiono kilka zadań do wypróbowania: