Začínáme se správou verzí

Článek
01/10/2024

Použití verzí s manifesty

Začněme vytvořením jednoduchého projektu CMake, který závisí na fmt a zlib.

Vytvořte složku s následujícími soubory:

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)

A teď sestavíme a spustíme projekt pomocí CMake:

Vytvořte adresář sestavení pro projekt.

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

Nakonfigurujte 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
...

Sestavte projekt.

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

Spusťte ho!

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

Podívejte se na výstup:

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

Místo použití souborů portů v ports/, vcpkg si soubory pro každou verzi v buildtrees/versioning/versions/. Soubory v ports/ se stále používají při spouštění vcpkg v klasickém režimu.

Poznámka

Výstup z vcpkg při konfiguraci CMake je k dispozici pouze při použití verze CMake 3.18 nebo novější. Pokud používáte starší CMake, můžete místo toho zkontrolovat soubor vcpkg-manifest-install.log v adresáři sestavení.

Přečtěte si blogovém příspěvku o oznámení manifestů , kde se dozvíte, jak používat manifesty s nástrojem MSBuild.

Změny manifestu

Pokud jste dříve použili manifesty, všimněte si, že existují některé nové vlastnosti JSON. Pojďme se podívat na tyto změny:

`version`

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

Toto je deklarace verze projektu. Dříve bylo možné deklarovat pouze verze projektů pomocí vlastnosti version-string. Teď, když se správa verzí obejde, vcpkg ví o některých nových schématech správy verzí.

Schéma verzí	Popis
`version`	Číslice oddělené tečkami: `1.0.0.5`.
`version-semver`	Kompatibilní sémantické verze: `1.2.0` a `1.2.0-rc`.
`version-date`	Data ve formátu `YYYY-MM-DD`: `2021-01-01`
`version-string`	Libovolné řetězce: `vista`, `candy`.

`version>=`

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

Tato vlastnost se používá k vyjádření minimálních omezení verze, je povolená pouze v rámci deklarací "dependencies". V našem příkladu nastavíme explicitní omezení verze 7.1.3#1fmt.

Vcpkg může toto omezení upgradovat, pokud tranzitivní závislost vyžaduje novější verzi. Pokud by například zlib deklarovaly závislost na fmt verzi 7.1.4 pak by se místo toho nainstalovala 7.1.4 vcpkg.

Vcpkg používá v našem příkladu přístup s minimální verzí, i když fmt verze 8.0.0 byla vydána, vcpkg by stále nainstaloval verzi 7.1.3#1, protože to je minimální verze, která splňuje omezení. Výhodou tohoto přístupu je, že při aktualizaci vcpkg nezískáte neočekávané upgrady závislostí a získáte reprodukovatelné buildy (pokud se používá verze), pokud použijete stejný manifest.

Pokud chcete upgradovat závislosti, můžete přejít na omezení minimální verze nebo použít novější směrný plán.

`builtin-baseline`

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

Toto pole deklaruje směrný plán správy verzí pro všechny porty. Nastavení směrného plánu je nutné k povolení správy verzí, jinak získáte aktuální verze v adresáři ports/. Spuštěním příkazu git rev-parse HEAD můžete získat aktuální potvrzení vcpkg a nastavit ho jako předdefinovaný směrný plán. Další informace najdete v dokumentaci "builtin-baseline".

V našem příkladu nehlásíme omezení verze pro zlib; místo toho je verze převzata ze směrného plánu. Interně bude vcpkg hledat potvrzení 3426db05b996481ca31e95fff3734cf23e0f51bc zjistit, jaká verze zlib byla v daném okamžiku nejnovější (v našem případě to bylo 1.2.11#9).

Během řešení verzí se základní verze považují za omezení minimální verze. Pokud deklarujete explicitní omezení, které je nižší než základní verze, explicitní omezení se upgraduje na základní verzi.

Pokud jsme například upravili závislosti takto:

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

Poznámka

Hodnota 1.2.11#7 představuje verzi 1.2.11, 7verze portu .

Vzhledem k tomu, že směrný plán zavádí omezení minimální verze pro zlib na 1.2.11#9 a vyšší verze splňuje omezení minimální verze pro 1.2.11#7, vcpkg ho může upgradovat.

Standardní hodnoty jsou také pohodlným mechanismem upgradu více verzí najednou, například pokud chcete záviset na více boost knihovnách, je vhodnější nastavit baseline jednou než deklarovat omezení verze u každého balíčku.

Ale co když chcete připnout verzi starší než standardní hodnoty?

`overrides`

Vzhledem k tomu, že směrné plány stanoví úroveň verze pro všechny balíčky a explicitní omezení se upgradují, když jsou nižší než standardní hodnoty, potřebujeme další mechanismus downgradu verzí za směrný plán.

Mechanismus vcpkg pro tento scénář je overrides. Pokud je přepsání deklarováno v balíčku, vcpkg ignoruje všechna ostatní omezení verze buď přímo deklarovaná v manifestu, nebo z tranzitivních závislostí. Stručně řečeno, overrides vcpkg vcpkg použije přesnou verzi deklarovanou, tečku.

Pojďme náš příklad ještě jednou upravit, tentokrát vynutit použití verze 6.0.0fmt.

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

Znovu sestavte 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

A spusťte ho!

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

Všimněte si, že fmt je teď ve verzi 6.0.0 stejně jako jsme chtěli.

Verze a vlastní porty

Poslední věcí, kterou je potřeba prodiskutovat, je interakce překryvných portů s řešením správy verzí. Odpověď je: oni ne.

Když zadáte překryvný port, bude vcpkg vždy používat překryvný port bez starostí o verzi, která je v něm obsažená. Důvody jsou dvounásobné: (1) je konzistentní se stávajícím chováním překryvných portů, které zcela maskují stávající port, a (2) překryvné porty neposkytují (a neočekávají) dostatek informací pro funkci správy verzí vcpkg.

Pokud chcete mít flexibilní přizpůsobení portů spolu s správou verzí, měli byste zvážit vytvoření vlastního registru.

Další čtení

Pokud vás zajímají podrobnější informace o tom, jak funguje správa verzí, doporučujeme, abyste si přečetli referenční informace o správy verzí a koncepty správy verzí .

Sdílet prostřednictvím