Dokumentacja dotycząca przechowywania wersji
Przechowywanie wersji umożliwia deterministyczne kontrolowanie dokładnych poprawek zależności używanych przez projekt z poziomu pliku manifestu. Przechowywanie wersji jest dostępne tylko dla użytkowników trybu manifestu.
Aby uzyskać więcej informacji na temat algorytmu przechowywania wersji vcpkg i pojęć wysokiego poziomu, zobacz Pojęcia dotyczące przechowywania wersji.
Aby zapoznać się z przykładem z kontekstem, zapoznaj się z naszym przewodnikiem dotyczącym rozpoczynania pracy z przechowywaniem wersji.
Schematy wersji
Porty w programie vcpkg powinny próbować przestrzegać konwencji przechowywania wersji używanych przez autorów pakietu. Z tego powodu podczas deklarowania wersji pakietu należy użyć odpowiedniego schematu.
Każdy schemat przechowywania wersji definiuje własne reguły dotyczące prawidłowego ciągu wersji i co ważniejsze reguły sortowania wersji przy użyciu tego samego schematu.
Schematy przechowywania wersji zrozumiałe przez program vcpkg to:
| Właściwość manifestu | Schemat przechowywania wersji |
|---|---|
version |
W przypadku wersji liczbowych rozdzielonych kropkami |
version-semver |
W przypadku wersji zgodnych ze standardem SemVer |
version-date |
W przypadku dat w formacie YYYY-MM-DD |
version-string |
W przypadku dowolnych ciągów |
Manifest musi zawierać tylko jedną deklarację wersji.
Uwaga
Zgodnie z projektem program vcpkg nie porównuje wersji korzystających z różnych schematów. Na przykład pakiet, którego version-string: 7.1.3 nie można porównać z tym samym pakietem przy użyciu polecenia version: 7.1.4, nawet jeśli konwersja wydaje się oczywista.
version
Akceptuje ciągi wersji, które są zgodne ze schematem zrelaksowanym, rozdzielonym kropką, semver-like.
Wersja składa się logicznie z rozdzielanych kropkami (.) sekcji liczbowych. Każda sekcja musi zawierać liczbę całkowitą dodatnią bez zer wiodących.
Wzorzec wyrażeń regularnych dla tego schematu przechowywania wersji to: (0|[1-9]\d*)(\.(0|[1-9]\d*))*
Zachowanie sortowania: podczas porównywania dwóch wersji każda sekcja jest porównywana od lewej do prawej według ich wartości liczbowej do momentu znalezienia pierwszej różnicy. Wersja z najmniejszym zestawem sekcji ma pierwszeństwo przed innym z większym zestawem sekcji, biorąc pod uwagę, że wszystkie poprzednie sekcje są porównywane w równym stopniu.
Przykład:
0 < 0.1 < 0.1.0 < 1 < 1.0.0 < 1.0.1 < 1.1< 2.0.0
version-semver
Akceptuje ciągi wersji, które są zgodne z semantycznymi konwencjami przechowywania wersji zgodnie z opisem w specyfikacji semantycznej przechowywania wersji.
Zachowanie sortowania: ciągi są sortowane zgodnie z regułami opisanymi w specyfikacji semantycznej przechowywania wersji.
Przykład:
1.0.0-1 < 1.0.0-alpha < 1.0.0-beta < 1.0.0 < 1.0.1 < 1.1.0
version-date
Akceptuje ciągi wersji, które można przeanalizować do daty po formacie YYYY-MM-DDISO-8601. Identyfikatory uściślania są dozwolone w postaci cyfr rozdzielanych kropkami, dodatnimi, liczbami całkowitymi bez zer wiodących.
Jest to zalecany schemat przechowywania wersji dla bibliotek "Live at HEAD", które nie mają ustanowionych wersji wydania.
Wzorzec wyrażeń regularnych dla tego schematu przechowywania wersji to: \d{4}-\d{2}-\d{2}(\.(0|[1-9]\d*))*
Zachowanie sortowania: ciągi są sortowane najpierw według ich części daty, a następnie według liczbowego porównania identyfikatorów uściślania. Identyfikatory uściślania są zgodne z zasadami schematu złagodzonego (version).
Przykłady: 2021-01-01<2021-01-01.1<2021-02-01.1.2<2021-02-01.1.3<2021-02-01
version-string
W przypadku pakietów korzystających z ciągów wersji, które nie pasują do żadnego z innych schematów, akceptuje większość dowolnych ciągów. Element # używany do oznaczania wersji portów jest niedozwolony.
Zachowanie sortowania: nie podjęto próby sortowania w samym ciągu wersji. Jeśli jednak ciągi są dokładnie zgodne, ich wersje portów można porównać i posortować.
Przykłady:
apple<>orange<>orange.2<>orange2watermelon#0<watermelon#1
port-version
Wersje portów śledzą zmiany w plikach pakietów (vcpkg.json, portfile.cmakeitp.) bez żadnych zmian w nadrzędnej wersji biblioteki.
Wersja portu to nieujemna wartość całkowita.
Reguły dotyczące wersji portów to:
- Zacznij od 0 dla oryginalnej wersji portu,
- zwiększ o 1 za każdym razem, gdy następuje zmiana specyficzna dla programu vcpkg na porcie, który nie zwiększa wersji pakietu,
- i zresetuj wartość 0 za każdym razem, gdy wersja pakietu zostanie zaktualizowana.
Uwaga
Program vcpkg jest zgodny z formatem <version>#<port version>tekstu . Na przykład 1.2.0#2 oznacza wersję 1.2.02portu . Jeśli wersja portu to 0#0 sufiks zostanie pominięty (np. 1.2.0 oznacza wersję portu wersji 1.2.00).
Zachowanie sortowania: jeśli dwie wersje są porównywane w równym stopniu, ich wersje portów są porównywane według ich wartości liczbowej, niższe wersje portów mają pierwszeństwo.
Przykłady:
1.2.0<1.2.0#1<1.2.0#2<1.2.0#102021-01-01#20<2021-01-01.1windows#7<windows#8
Ograniczenia wersji
Podstaw
Punkty odniesienia definiują globalną podłogę wersji dla wersji, które będą brane pod uwagę. Dzięki temu manifesty najwyższego poziomu zapewniają aktualność całego grafu zależności bez konieczności indywidualnego określania bezpośrednich "version>=" ograniczeń.
Każdy skonfigurowany rejestr ma skojarzony punkt odniesienia. W przypadku manifestów, które nie konfigurują żadnych rejestrów, "builtin-baseline" pole definiuje punkt odniesienia wbudowanego rejestru. Jeśli manifest nie konfiguruje żadnych rejestrów i nie ma "builtin-baseline", instalacja działa zgodnie z algorytmem trybu klasycznego i ignoruje wszystkie informacje dotyczące przechowywania wersji.
Punkty odniesienia, takie jak inne ustawienia rejestru, są ignorowane z portów używanych jako zależność. Jeśli wymagana jest minimalna wersja podczas przejściowego rozpoznawania wersji, port powinien używać polecenia "version>=".
Przykład
{
"name": "project",
"version": "1.0.0",
"dependencies": ["zlib", "fmt"],
"builtin-baseline":"9fd3bd594f41afb8747e20f6ac9619f26f333cbe"
}
Aby dodać początkowy element "builtin-baseline", użyj polecenia vcpkg x-update-baseline --add-initial-baseline. Aby zaktualizować punkty odniesienia w manifeście, użyj polecenia vcpkg x-update-baseline.
version>=
Wyraża minimalne wymaganie dotyczące wersji, version>= deklaracje nakładają niższą granicę na wersje, których można użyć do spełnienia zależności.
Uwaga
Narzędzie vcpkg wybiera najniższą wersję zgodną ze wszystkimi ograniczeniami, więc ograniczenie mniejsze niż jest wymagane.
Przykład:
{
"name": "project",
"version-semver": "1.0.0",
"dependencies": [
{ "name": "zlib", "version>=": "1.2.11#9" },
{ "name": "fmt", "version>=": "7.1.3#1" }
],
"builtin-baseline":"3426db05b996481ca31e95fff3734cf23e0f51bc"
}
W ramach deklaracji ograniczenia wersji można określić wersję portu, dodając sufiks #<port-version>, w poprzednim przykładzie 1.2.11#9 odnosi się do wersji portu wersji 1.2.119.
overrides
Deklarowanie przesłonięcia wymusza, aby program vcpkg ignorował wszystkie inne ograniczenia wersji i używał wersji określonej w zastąpieniu. Jest to przydatne w przypadku przypinania dokładnych wersji i rozwiązywania konfliktów wersji.
Przesłonięcia są deklarowane jako tablica deklaracji wersji pakietu.
Aby przesłonięcia zaczęły obowiązywać, przesłonięć pakiet musi stanowić część grafu zależności. Oznacza to, że zależność musi być zadeklarowana przez manifest najwyższego poziomu lub być częścią zależności przechodniej.
{
"name": "project",
"version-semver": "1.0.0",
"dependencies": [
"curl",
{ "name": "zlib", "version>=": "1.2.11#9" },
"fmt"
],
"builtin-baseline":"3426db05b996481ca31e95fff3734cf23e0f51bc",
"overrides": [
{ "name": "fmt", "version": "6.0.0" },
{ "name": "openssl", "version": "1.1.1h#3" }
]
}
