Dokumentacja rejestrów

Omówienie

W tym artykule opisano szczegóły implementacji dla każdego rodzaju rejestru. W szczególności ten plik dotyczy zalecanego układu dla każdego rodzaju rejestru i oczekiwanej zawartości odpowiedniej bazy danych wersji.

Rejestry usługi Git

Układ pliku punktu odniesienia w rejestrach usługi Git

Pola najwyższego poziomu

Obiekt najwyższego baseline.json poziomu w pliku jest słownikiem, każdy klucz w tym słowniku jest nazwanym punktem odniesienia. Ze względu na szczegóły implementacji rejestrów Git wymagane jest, aby nazwany punkt odniesienia o nazwie "default" istnieje i że zawiera mapowanie wszystkich portów w rejestrze do ich wersji bazowej.

BaselineObject

Obiekt punktu odniesienia jest słownikiem, z każdym kluczem odpowiadającym nazwie portu w rejestrze i jego wartością jest najnowsza wersja portu.

BaselineVersionObject

baseline.json Przykład pliku w rejestrze Git

W rejestrze zawierającym pojedynczy port o nazwie foo w wersji 1.0.0#1baseline.json zawartość pliku powinna być następująca:

{
  "default": {
    "foo": { 
      "baseline": "1.0.0", 
      "port-version": 1
    }
  }
}

Układ pliku wersji w rejestrach usługi Git

Katalog versions zawiera wszystkie informacje o tym, które wersje pakietów znajdują się w rejestrze, wraz z metodą pobierania tych wersji z historii repozytorium.

Plik wersji dla każdego pakietu jest plikiem JSON o tej samej nazwie podstawowej co pakiet, umieszczonym w podkatalogu katalogu versions, który jest pierwszą literą pakietu, a następnie kreską. Na przykład plik wersji pakietu pcre2 to versions\p-\pcre2.json.

Pola najwyższego poziomu

VersionObject

Przykład pliku wersji rejestru Git

{
  "versions": [
    {
      "git-tree": "963060040c3ca463d17136e39c7317efb15eb6a5",
      "version": "1.2.0",
      "port-version": 0
    },
    {
      "git-tree": "548c90710d59c174aa9ab10a24deb69f1d75ff8f",
      "version": "1.1.0",
      "port-version": 0
    },
    {
      "git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e",
      "version": "1.0.0",
      "port-version": 0
    }
  ]
}

Uzyskiwanie algorytmu git-tree SHA

Narzędzie vcpkg używa funkcji usługi Git do pobierania określonych wersji portu zawartego w historii zatwierdzeń. Używana metoda polega na pobraniu git-tree obiektu z repozytorium, jak określono w pliku wersji portu.

Każdy katalog portów w rejestrze Git ma skojarzony unikatowy algorytm SHA (określany jako git-tree w plikach wersji). Sha jest obliczany przy użyciu zawartości katalogu; za każdym razem, gdy zmiana jest zatwierdzana w repozytorium, które modyfikuje katalog, jego algorytm SHA jest ponownie obliczany.

Usługa Git umożliwia pobranie zawartości danego katalogu w dowolnym momencie jego historii, pod warunkiem, że znasz ich konkretny algorytm SHA. Korzystając z tej funkcji, narzędzie vcpkg może indeksować określone wersje portów przy użyciu odpowiedniego algorytmu SHA (git-tree).

Aby uzyskać algorytm SHA katalogu portów w dowolnej wersji, można użyć następującego polecenia Git:

git -C <path/to/ports> ls-tree --format='%(objectname)' <commit sha> -- <portname>

Przykład:

git -C %VCPKG_ROOT%/ports ls-tree --format='%(objectname)' HEAD -- curl
6ef1763f3cbe570d6378632c9b5793479c37fb07

Polecenie zwraca sha SHA katalogu zawierającego curl port w bieżącej wersji (HEAD).

Można wyświetlić zawartość git-tree polecenia przy użyciu polecenia git show <git-tree>:

git show 6ef1763f3cbe570d6378632c9b5793479c37fb07
tree 6ef1763f3cbe570d6378632c9b5793479c37fb07

0005_remove_imp_suffix.patch
0020-fix-pc-file.patch
0022-deduplicate-libs.patch
cmake-config.patch
cmake-project-include.cmake
dependencies.patch
export-components.patch
portfile.cmake
redact-input-vars.diff
usage
vcpkg-cmake-wrapper.cmake
vcpkg.json

Lub zawartość określonego pliku z git show <git-tree>:<file>:

git show 6ef1763f3cbe570d6378632c9b5793479c37fb07:usage
curl is compatible with built-in CMake targets:

    find_package(CURL REQUIRED)
    target_link_libraries(main PRIVATE CURL::libcurl)

Zarządzanie aktualnymi plikami bazy danych przy użyciu tych poleceń git w procesie ręcznym może być trudnym zadaniem. Z tego powodu zalecamy użycie x-add-version polecenia , które automatyzuje proces, o ile repozytorium jest zgodne z zalecaną strukturą rejestru. Zobacz samouczek: publikowanie pakietów w prywatnym rejestrze vcpkg przy użyciu usługi Git , aby zapoznać się z przykładem publikowania portu w rejestrze Git.

Rejestry systemu plików

Układ pliku punktu odniesienia w rejestrach systemu plików

Pola najwyższego poziomu

Obiekt najwyższego baseline.json poziomu w pliku jest słownikiem, każdy klucz w tym słowniku jest nazwanym punktem odniesienia. Punkty odniesienia powinny zawierać mapowania wszystkich portów w rejestrze do ich wersji punktu odniesienia.

BaselineObject

Obiekt punktu odniesienia jest słownikiem, z każdym kluczem odpowiadającym nazwie portu w rejestrze i jego wartością jest najnowsza wersja portu.

BaselineVersionObject

Układ pliku punktu odniesienia w rejestrze systemu plików jest taki sam jak w przypadku rejestrów git. Jedyną różnicą default jest to, że systemy plików nie wymagają punktu odniesienia.

baseline.json Przykład pliku w rejestrze systemu plików

{
  "2024-12-01": {
    "foo": {
      "baseline": "1.0.0",
      "port-version": 1
    }
  }
}

Układ pliku wersji w rejestrach systemu plików

Katalog versions zawiera wszystkie informacje o tym, które wersje pakietów znajdują się w rejestrze, wraz z metodą pobierania tych wersji z lokalizacji systemu plików.

Plik wersji dla każdego pakietu jest plikiem JSON o tej samej nazwie podstawowej co pakiet, umieszczonym w podkatalogu katalogu versions, który jest pierwszą literą pakietu, a następnie kreską. Na przykład plik wersji pakietu fmt to versions\f-\fmt.json.

Pola najwyższego poziomu

VersionObject

Podczas określania path rejestru $ można użyć znaku w celu odwołania się do katalogu głównego rejestru. W przeciwnym razie można użyć ścieżek bezwzględnych.

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

Dalsze kroki

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

• Przeczytaj dokumentację koncepcyjną rejestrów
• Tworzenie własnego rejestru opartego na usłudze Git
• Instalowanie pakietów z rejestru niestandardowego