Wprowadzenie do przechowywania wersji

Artykuł
01/10/2024

Używanie wersji z manifestami

Zacznijmy od utworzenia prostego projektu narzędzia CMake, który zależy od fmt elementów i zlib.

Utwórz folder z następującymi plikami:

vcpkg.json

{
    "name": "versions-test",
    "version": "1.0.0",
    "dependencies": [
        {
            "name": "fmt",
            "version>=": "7.1.3#1"
        }, 
        "zlib"
    ],
    "builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc"
}

main.cpp

#include <fmt/core.h>
#include <zlib.h>

int main()
{
    fmt::print("fmt version is {}\n"
               "zlib version is {}\n", 
               FMT_VERSION, ZLIB_VERSION);
    return 0;
}

CMakeLists.txt

cmake_minimum_required(VERSION 3.18)

project(versionstest CXX)

add_executable(main main.cpp)

find_package(ZLIB REQUIRED)
find_package(fmt CONFIG REQUIRED)
target_link_libraries(main PRIVATE ZLIB::ZLIB fmt::fmt)

Teraz skompilujemy i uruchomimy nasz projekt za pomocą narzędzia CMake:

Utwórz katalog kompilacji dla projektu.

PS D:\versions-test> mkdir build
PS D:\versions-test> cd build

Konfigurowanie narzędzia CMake.

PS D:\versions-test\build> cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=D:/vcpkg/scripts/buildsystems/vcpkg.cmake ..
-- Running vcpkg install
Detecting compiler hash for triplet x86-windows...
The following packages will be built and installed:
    fmt[core]:x64-windows -> 7.1.3#1 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\fmt\4f8427eb0bd40da1856d4e67bde39a4fda689d72
    vcpkg-cmake[core]:x64-windows -> 2021-02-26 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\vcpkg-cmake\51896aa8073adb5c8450daa423d03eedf0dfc61f
    vcpkg-cmake-config[core]:x64-windows -> 2021-02-26 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\vcpkg-cmake-config\d255b3d566a8861dcc99a958240463e678528066
    zlib[core]:x64-windows -> 1.2.11#9 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\zlib\827111046e37c98153d9d82bb6fa4183b6d728e4
...

Skompiluj projekt.

PS D:\versions-test\build> cmake --build .
[2/2] Linking CXX executable main.exe

Uruchom go!

PS D:\versions-test\build> ./main.exe
fmt version is 70103
zlib version is 1.2.11

Przyjrzyj się danym wyjściowym:

fmt[core]:x86-windows -> 7.1.3#1 -- D:\vcpkg\buildtrees\versioning\versions\fmt\4f8427eb0bd40da1856d4e67bde39a4fda689d72
...
zlib[core]:x86-windows -> 1.2.11#9 -- D:\vcpkg\buildtrees\versioning\versions\zlib\827111046e37c98153d9d82bb6fa4183b6d728e4

Zamiast używać plików portfile w pliku ports/, program vcpkg wyewidencjonuje pliki dla każdej wersji w programie buildtrees/versioning/versions/. Pliki w programie ports/ są nadal używane podczas uruchamiania narzędzia vcpkg w trybie klasycznym.

Uwaga

Dane wyjściowe z narzędzia vcpkg podczas konfigurowania narzędzia CMake są dostępne tylko w przypadku korzystania z wersji 3.18 narzędzia CMake lub nowszej. Jeśli używasz starszego narzędzia CMake, możesz zamiast tego sprawdzić vcpkg-manifest-install.log plik w katalogu kompilacji.

Przeczytaj nasz wpis w blogu z ogłoszeniem o manifestach, aby dowiedzieć się, jak używać manifestów w programie MSBuild.

Zmiany manifestu

Jeśli wcześniej użyto manifestów, zauważysz, że istnieją pewne nowe właściwości JSON. Przejrzyjmy następujące zmiany:

`version`

{
    "name": "versions-test",
    "version": "1.0.0"
}

Jest to deklaracja wersji projektu. Wcześniej można było zadeklarować tylko wersje projektów przy użyciu version-string właściwości . Teraz, gdy obsługa wersji nadeszła, vcpkg jest świadomy niektórych nowych schematów przechowywania wersji.

Schemat wersji	opis
`version`	Cyfry rozdzielone kropkami: `1.0.0.5`.
`version-semver`	Zgodne wersje semantyczne: `1.2.0` i `1.2.0-rc`.
`version-date`	Daty w `YYYY-MM-DD` formacie: `2021-01-01`
`version-string`	Dowolne ciągi: `vista`, `candy`.

`version>=`

{
    "dependencies": [
        { "name": "fmt", "version>=": "7.1.3" },
        "zlib"
    ]
}

Ta właściwość jest używana do wyrażania minimalnych ograniczeń wersji, jest dozwolona tylko w ramach "dependencies" deklaracji. W naszym przykładzie ustawiliśmy jawne ograniczenie dla wersji 7.1.3#1 .fmt

Program vcpkg może uaktualnić to ograniczenie, jeśli zależność przechodnia wymaga nowszej wersji. Jeśli na przykład zadeklarować zależność od wersji, zlib zamiast tego program vcpkg zostanie zainstalowany7.1.4.7.1.4fmt

W naszym przykładzie narzędzie vcpkg używa minimalnej wersji, nawet jeśli fmt wersja 8.0.0 ma zostać wydana, narzędzie vcpkg nadal będzie instalować wersję 7.1.3#1 , ponieważ jest to minimalna wersja, która spełnia ograniczenie. Zaletą tego podejścia jest to, że nie otrzymujesz nieoczekiwanych uaktualnień zależności podczas aktualizacji programu vcpkg i uzyskujesz odtwarzalne kompilacje (w kategoriach używanej wersji), o ile używasz tego samego manifestu.

Jeśli chcesz uaktualnić zależności, możesz podnieść ograniczenie minimalnej wersji lub użyć nowszego punktu odniesienia.

`builtin-baseline`

{ "builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc" }

To pole deklaruje plan bazowy przechowywania wersji dla wszystkich portów. Ustawienie punktu odniesienia jest wymagane do włączenia przechowywania wersji. W przeciwnym razie będziesz otrzymywać bieżące wersje w ports/ katalogu. Możesz uruchomić polecenie "git rev-parse HEAD", aby uzyskać bieżące zatwierdzenie narzędzia vcpkg i ustawić je jako wbudowany punkt odniesienia. Aby uzyskać więcej informacji, zobacz dokumentację"builtin-baseline".

W naszym przykładzie nie deklarujemy ograniczenia wersji dla zlibelementu ; zamiast tego wersja jest pobierana z punktu odniesienia. Wewnętrznie vcpkg będzie szukać w zatwierdzeniu 3426db05b996481ca31e95fff3734cf23e0f51bc , aby dowiedzieć się, jaka wersja zlib była najnowsza w tym momencie w czasie (w naszym przypadku było 1.2.11#9to ).

Podczas rozwiązywania wersji wersje bazowe są traktowane jako minimalne ograniczenia wersji. Jeśli zadeklarujesz jawne ograniczenie, które jest niższe niż wersja punktu odniesienia, jawne ograniczenie zostanie uaktualnione do wersji punktu odniesienia.

Jeśli na przykład zmodyfikowaliśmy nasze zależności w następujący sposób:

{ "dependencies": [
    {
        "name": "fmt",
        "version>=": "7.1.3#1"
    },
    {
        "name": "zlib",
        "version>=": "1.2.11#7"
    }
] }

Uwaga

Wartość 1.2.11#7 reprezentuje wersję , wersję 1.2.117portu .

Ponieważ w punkcie odniesienia wprowadzono ograniczenie minimalnej wersji dla zlib programu , 1.2.11#9 a wyższa wersja spełnia minimalne ograniczenie wersji dla 1.2.11#7programu , program vcpkg może go uaktualnić.

Punkty odniesienia są również wygodnym mechanizmem uaktualniania wielu wersji naraz, na przykład jeśli chcesz zależeć od wielu boost bibliotek, wygodniejsze jest ustawienie baseline raz niż deklarowanie ograniczenia wersji dla każdego pakietu.

Ale co zrobić, jeśli chcesz przypiąć wersję starszą niż punkt odniesienia?

`overrides`

Ponieważ linie bazowe ustanawiają podłogę wersji dla wszystkich pakietów i jawnych ograniczeń są uaktualniane, gdy są niższe niż punkt odniesienia, potrzebujemy innego mechanizmu, aby obniżyć wersje przeszłości punktu odniesienia.

Mechanizm vcpkg zapewnia dla tego scenariusza wartość overrides. Po zadeklarowaniu przesłonięcia w pakiecie program vcpkg zignoruje wszystkie inne ograniczenia wersji bezpośrednio zadeklarowane w manifeście lub z przejściowych zależności. Krótko mówiąc, overrides wymusi użycie dokładnej zadeklarowanej wersji, okresu vcpkg.

Zmodyfikujmy jeszcze raz nasz przykład, tym razem, aby wymusić użycie wersji programu vcpkg w fmtwersji 6.0.0 .

{
    "name": "versions-test",
    "version": "1.0.0",
    "dependencies": [
        {
            "name": "fmt",
            "version>=": "7.1.3#1"
        },
        {
            "name": "zlib",
            "version>=": "1.2.11#7"
        }
    ],
    "builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc",
    "overrides": [
        {
            "name": "fmt",
            "version": "6.0.0"
        }
    ]
}

Skompiluj nasz projekt:

PS D:\versions-test\build> rm ./CMakeCache.txt
PS D:\versions-test\build> rm -r ./vcpkg_installed
PS D:\versions-test\build> cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=D:/vcpkg/scripts/buildsystems/vcpkg.cmake ..
-- Running vcpkg install
Detecting compiler hash for triplet x86-windows...
The following packages will be built and installed:
    fmt[core]:x86-windows -> 6.0.0 -- D:\vcpkg\buildtrees\versioning\versions\fmt\d99b6a35e1406ba6b6e09d719bebd086f83ed5f3
    zlib[core]:x86-windows -> 1.2.11#9 -- D:\vcpkg\buildtrees\versioning\versions\zlib\827111046e37c98153d9d82bb6fa4183b6d728e4
...
PS D:\versions-test\build> cmake --build .
[2/2] Linking CXX executable main.exe

I uruchomić go!

PS D:\versions-test\build> .\main.exe
fmt version is 60000
zlib version is 1.2.11

Zwróć uwagę, że element fmt jest teraz w wersji 6.0.0 tak jak chcieliśmy.

Wersje i porty niestandardowe

Ostatnią rzeczą do omówienia jest sposób interakcji portów nakładki z rozpoznawaniem wersji. Odpowiedź brzmi: nie.

Przechodząc do bardziej szczegółowych informacji, gdy podasz nakładkę dla portu, vcpkg zawsze będzie używać portu nakładki bez dbania o to, jaka wersja jest zawarta w nim. Przyczyny są dwa razy: (1) jest zgodne z istniejącym zachowaniem portów nakładki całkowitego maskowania istniejącego portu, a (2) porty nakładki nie (i nie powinny) dostarczać wystarczającej ilości informacji do obsługi wersji funkcji vcpkg.

Jeśli chcesz mieć elastyczne dostosowywanie portów wraz z przechowywaniem wersji, rozważ utworzenie własnego rejestru niestandardowego.

Dalsze informacje

Jeśli chcesz zagłębić się w szczegółowe informacje na temat sposobu działania przechowywania wersji, zalecamy zapoznanie się z naszymi pojęciami dotyczącymi przechowywania wersji i przechowywaniem wersji.

Udostępnij za pośrednictwem