Tworzenie rejestrów

Aby uzyskać informacje na temat korzystania z rejestrów, zobacz Korzystanie z rejestrów.

Omówienie

Rejestry to kolekcje portów i ich wersji. Istnieją dwa główne opcje implementacji dla rejestrów, jeśli chcesz utworzyć własne: rejestry git i rejestry systemu plików.

Rejestry git są prostymi repozytoriami Git i mogą być udostępniane publicznie lub prywatnie za pośrednictwem normalnych mechanizmów repozytoriów git. Na przykład repozytorium vcpkg jest rejestrem git.

Rejestry systemu plików są projektowane jako bardziej testowe grunty. Biorąc pod uwagę, że dosłownie żyją w systemie plików, jedynym sposobem ich udostępnienia jest użycie katalogów udostępnionych. Jednak rejestry systemu plików mogą być przydatne jako sposób reprezentowania rejestrów przechowywanych w systemach kontroli wersji innych niż git, przy założeniu, że istnieje jakiś sposób na pobranie rejestru na dysk.

Oczekujemy, że zestaw typów rejestru wzrośnie wraz z upływem czasu; Jeśli chcesz obsługiwać rejestry wbudowane w ulubiony publiczny system kontroli wersji, nie wahaj się otworzyć żądania ściągnięcia.

Podstawowa struktura rejestru to:

• Zestaw wersji, które są uznawane za "najnowsze" w niektórych momentach w historii, znany jako "punkt odniesienia".
• Zestaw wszystkich wersji wszystkich portów oraz miejsce, w którym można znaleźć każdy z nich w rejestrze.

Rejestry usługi Git

W miarę korzystania z tej dokumentacji warto zapoznać się z przykładem roboczym. Napisaliśmy jeden i umieściliśmy go tutaj:

Microsoft/vcpkg-docs: rejestr vcpkg.

Wszystkie rejestry git muszą mieć versions/baseline.json plik. Ten plik zawiera zestaw "najnowszych wersji" w określonym zatwierdzeniu. Jest on ułożony jako obiekt najwyższego poziomu zawierający tylko "default" pole. To pole powinno zawierać nazwy portów mapowania obiektów na wersję, która jest obecnie najnowsza.

Oto przykład prawidłowej baseline.json:

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

Katalog versions zawiera wszystkie informacje o tym, które wersje pakietów znajdują się w rejestrze, wraz z miejscami przechowywania tych wersji. Reszta rejestru działa tak samo jak magazyn zapasowy, jeśli chodzi o vcpkg: tylko elementy wewnątrz versions katalogu będą używane do kierowania sposobu, w jaki rejestr jest widoczny przez vcpkg.

Każdy port w rejestrze powinien istnieć w katalogu versions jako <first letter of port>-/<name of port>.json; innymi słowy, informacje o kitten porcie będą znajdować się w katalogu versions/k-/kitten.json. Powinien to być obiekt najwyższego poziomu z tylko jednym polem: "versions". To pole powinno zawierać tablicę obiektów wersji:

• Wersja danego portu; powinien być dokładnie taki sam jak vcpkg.json plik, w tym pola wersji i "port-version".
• Pole "git-tree" , które jest drzewem git; innymi słowy, co otrzymujesz podczas pisania git rev-parse COMMIT-ID:path/to/port.

Pole wersji dla portów z przestarzałymi CONTROL plikami to "version-string".

Ostrzeżenie

Jedną z bardzo ważnych części rejestrów jest to, że wersje nigdy nie powinny być zmieniane. Aktualizacja do późniejszego odwołania nigdy nie powinna usuwać ani zmieniać istniejącej wersji. Zawsze musi być bezpieczne, aby zaktualizować rejestr.

Oto przykład prawidłowej wersji bazy danych dla kitten portu z jedną wersją:

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

Ogólnie rzecz biorąc, nie jest ważne, gdzie umieszczasz katalogi portów. Jednak idiom w narzędziu vcpkg jest zgodny z wbudowanym rejestrem vcpkg: port kitten powinien zostać umieszczony w ports/kittenpliku .

Ostrzeżenie

Należy pamiętać o tym, że po zaktualizowaniu rejestru wszystkie poprzednie wersje powinny być również dostępne. Ponieważ użytkownik ustawi swój punkt odniesienia na identyfikator zatwierdzenia, ten identyfikator zatwierdzenia musi zawsze istnieć i być dostępny z zatwierdzenia HEAD, co jest rzeczywiście pobierane. Oznacza to, że zatwierdzenie HEAD powinno być elementem podrzędnym wszystkich poprzednich zatwierdzeń HEAD.

Wbudowane rejestry

Wbudowane rejestry są traktowane jako specjalne rejestry Git. Zamiast pobierać ze zdalnego adresu URL, wbudowane rejestry skonsultuj się z $VCPKG_ROOT/.git katalogiem klonu vcpkg. Używają obecnie wyewidencjonowany $VCPKG_ROOT/versions katalog jako źródło informacji o wersji.

Dodawanie nowej wersji

Istnieje pewne sztuczki git związane z tworzeniem nowej wersji portu. Najpierw należy wprowadzić pewne zmiany, zaktualizować "port-version" i regularne pole wersji zgodnie z potrzebami, a następnie przetestować polecenie za pomocą overlay-portspolecenia :

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

Po zakończeniu testowania należy upewnić się, że katalog znajduje się w obszarze purview usługi Git. W tym celu utworzysz tymczasowe zatwierdzenie:

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

Następnie pobierz identyfikator drzewa git katalogu:

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

Następnie możesz dodać tę wersję do bazy danych wersji. W górnej części elementu możesz dodać element (przy założeniu versions/k-/kitten.json, że dodajesz wersję 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"
    }
  ]
}

Następnie należy zmodyfikować plik versions/baseline.json przy użyciu nowej wersji:

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

i zmień bieżące zatwierdzenie:

> git commit --amend

a następnie podziel się z nami!

Rejestry systemu plików

W miarę korzystania z tej dokumentacji warto zapoznać się z przykładem roboczym. Napisaliśmy jeden i umieściliśmy go tutaj:

Przykładowy rejestr systemu plików.

Wszystkie rejestry systemu plików muszą mieć versions/baseline.json plik. Ten plik zawiera zestaw "najnowszych wersji" dla określonej wersji rejestru. Jest on określony jako obiekt najwyższego poziomu zawierający mapę z nazwy wersji na "obiekty odniesienia", który mapuje nazwy portów na wersję, która jest uznawana za "najnowszą" dla tej wersji rejestru.

Rejestry systemu plików muszą zdecydować o schemacie przechowywania wersji. W przeciwieństwie do rejestrów git, które mają niejawny schemat przechowywania wersji ref, rejestry systemu plików nie mogą w tym miejscu polegać na systemie kontroli wersji. Jedną z możliwych opcji jest wykonywanie codziennego wydania, a twoje "wersje" mają daty.

Ostrzeżenie

Punkt odniesienia nie może być modyfikowany po opublikowaniu. Jeśli chcesz zmienić lub zaktualizować wersje, musisz utworzyć nowy punkt odniesienia w baseline.json pliku.

Oto przykład prawidłowego baseline.jsonrejestru, który zdecydował się na daty dla ich wersji:

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

Katalog versions zawiera wszystkie informacje o tym, które wersje pakietów znajdują się w rejestrze, wraz z miejscami przechowywania tych wersji. Reszta rejestru działa tak samo jak magazyn zapasowy, jeśli chodzi o vcpkg: tylko elementy wewnątrz versions katalogu będą używane do kierowania sposobu, w jaki rejestr jest widoczny przez vcpkg.

Każdy port w rejestrze powinien istnieć w katalogu versions jako <first letter of port>-/<name of port>.json; innymi słowy, informacje o kitten porcie będą znajdować się w katalogu versions/k-/kitten.json. Powinien to być obiekt najwyższego poziomu z tylko jednym polem: "versions". To pole powinno zawierać tablicę obiektów wersji:

• Wersja danego portu; powinien być dokładnie taki sam jak vcpkg.json plik, w tym pola wersji i "port-version".
• "path" Pole: katalog względny, zakorzeniony w bazie rejestru (innymi słowy, katalog, w którym versions się znajduje), do katalogu portów. Powinien wyglądać mniej więcej tak: "$/path/to/port/dir"

Pole wersji dla portów z przestarzałymi CONTROL plikami to "version-string".

Ogólnie rzecz biorąc, nie jest ważne, gdzie umieszczasz katalogi portów. Jednak idiom w narzędziu vcpkg jest nieco ściśle zgodny z tym, co robi wbudowany rejestr vcpkg: port kitten w wersji x.y.z należy umieścić w ports/kitten/x.y.zpliku , z dołączonymi wersjami portów, które są zgodne (chociaż ponieważ # nie jest dobrym znakiem do użycia dla nazw plików, być może użyj polecenia _).

Ostrzeżenie

Jedną z bardzo ważnych części rejestrów jest to, że wersje nigdy nie powinny być zmieniane. Nigdy nie należy usuwać ani zmieniać istniejącej wersji. Zmiany w rejestrze nie powinny zmieniać zachowania użytkowników podrzędnych.

Oto przykład prawidłowej wersji bazy danych dla kitten portu z jedną wersją:

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

Dodawanie nowej wersji

W przeciwieństwie do rejestrów git, dodanie nowej wersji do rejestru systemu plików wymaga głównie dużej ilości kopii. Najpierw należy skopiować najnowszą wersję portu do nowego katalogu wersji, zaktualizować wersję i "port-version" pola zgodnie z potrzebami overlay-ports, a następnie przetestować polecenie :

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

Po zakończeniu testowania możesz dodać tę nową wersję na początku elementu 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"
    }
  ]
}

Następnie należy zmodyfikować element versions/baseline.json przy użyciu nowej wersji (pamiętaj, aby nie modyfikować istniejących punktów odniesienia):

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

I gotowe!