Dela via

Komma igång med versionshantering

Använda versioner med manifest

Vi börjar med att skapa ett enkelt CMake-projekt som är beroende av fmt och zlib.

Skapa en mapp med följande filer:

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)

Och nu skapar och kör vi vårt projekt med CMake:

  1. Skapa byggkatalogen för projektet.

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

  2. Konfigurera 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
...

  3. Skapa projektet.

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

  4. Kör den!

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

Ta en titt på utdata:

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

I stället för att använda portfilerna i ports/checkar vcpkg ut filerna för varje version i buildtrees/versioning/versions/. Filerna i ports/ används fortfarande när du kör vcpkg i klassiskt läge.

Not

Utdata från vcpkg när du konfigurerar CMake är endast tillgängligt när du använder CMake-version 3.18 eller senare. Om du använder en äldre CMake kan du kontrollera vcpkg-manifest-install.log filen i byggkatalogen i stället.

Läs blogginlägget om manifestmeddelanden för att lära dig hur du använder manifest med MSBuild.

Manifeständringar

Om du har använt manifest innan kommer du att märka att det finns några nya JSON-egenskaper. Nu ska vi granska de här ändringarna:

version

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

Det här är projektets versionsdeklaration. Tidigare kunde du bara deklarera versioner för dina projekt med hjälp av egenskapen version-string. Nu när versionshantering har kommit runt är vcpkg medveten om några nya versionsscheman.

Versionsschema Beskrivning
version Punktavgränsade numeriska värden: 1.0.0.5.
version-semver Kompatibla semantiska versioner: 1.2.0 och 1.2.0-rc.
version-date Datum i YYYY-MM-DD format: 2021-01-01
version-string Godtyckliga strängar: vista, candy.

version>=

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

Den här egenskapen används för att uttrycka lägsta versionsbegränsningar. Den tillåts endast som en del av "dependencies"-deklarationerna. I vårt exempel anger vi en uttrycklig begränsning för version 7.1.3#1 av fmt.

vcpkg kan uppgradera den här begränsningen om ett transitivt beroende kräver en nyare version. Om zlib till exempel deklarerar ett beroende av fmt version 7.1.4 skulle vcpkg installera 7.1.4 i stället.

vcpkg använder en lägsta versionsmetod, i vårt exempel, även om fmt version 8.0.0 skulle släppas, skulle vcpkg fortfarande installera version 7.1.3#1 eftersom det är den lägsta versionen som uppfyller villkoret. Fördelarna med den här metoden är att du inte får oväntade beroendeuppgraderingar när du uppdaterar vcpkg och får reproducerbara versioner (när det gäller version som används) så länge du använder samma manifest.

Om du vill uppgradera dina beroenden kan du öka den lägsta versionsbegränsningen eller använda en nyare baslinje.

builtin-baseline

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

Det här fältet deklarerar versionsbaslinjen för alla portar. Du måste ange en baslinje för att aktivera versionshantering, annars får du de aktuella versionerna i katalogen ports/. Du kan köra "git rev-parse HEAD" för att hämta den aktuella incheckningen av vcpkg och ange den som inbyggd baslinje. Mer information finns i "builtin-baseline" dokumentation.

I vårt exempel deklarerar vi inte någon versionsbegränsning för zlib; i stället hämtas versionen från baslinjen. Internt tittar vcpkg i incheckningen 3426db05b996481ca31e95fff3734cf23e0f51bc för att ta reda på vilken version av zlib var den senaste vid den tidpunkten (i vårt fall var det 1.2.11#9).

Under versionsupplösningen behandlas baslinjeversioner som lägsta versionsbegränsningar. Om du deklarerar en explicit begränsning som är lägre än en baslinjeversion uppgraderas den explicita begränsningen till baslinjeversionen.

Om vi till exempel har ändrat våra beroenden så här:

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

Not

Värdet 1.2.11#7 representerar version 1.2.11, portversion 7.

Eftersom baslinjen introducerar en lägsta versionsbegränsning för zlib vid 1.2.11#9 och en högre version uppfyller den lägsta versionsbegränsningen för 1.2.11#7, tillåts vcpkg att uppgradera den.

Baslinjer är också en praktisk mekanism för att uppgradera flera versioner åt gången, till exempel om du vill vara beroende av flera boost bibliotek, är det enklare att ange baseline en gång än att deklarera en versionsbegränsning för varje paket.

Men vad händer om du vill fästa en version som är äldre än baslinjen?

overrides

Eftersom baslinjer upprättar en versionsvåning för alla paket och explicita begränsningar uppgraderas när de är lägre än baslinjen behöver vi en annan mekanism för att nedgradera versioner förbi baslinjen.

Mekanismen vcpkg tillhandahåller för det scenariot är overrides. När en åsidosättning deklareras för ett paket ignorerar vcpkg alla andra versionsbegränsningar antingen direkt deklarerade i manifestet eller från transitiva beroenden. Kort sagt, overrides tvingar vcpkg att använda den exakta versionen deklarerad, punkt.

Nu ska vi ändra vårt exempel en gång till, den här gången för att tvinga vcpkg att använda version 6.0.0 av fmt.

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

Återskapa vårt 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

Och kör den!

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

Observera hur fmt nu är i version 6.0.0 precis som vi ville.

Versioner och anpassade portar

Det sista du bör diskutera är hur överläggsportar interagerar med versionslösning. Svaret är: det gör de inte.

Om du går in mer i detalj, när du tillhandahåller ett överlägg för en port, kommer vcpkg alltid att använda överläggsporten utan att bry sig om vilken version som finns i den. Orsakerna är tvådelat: (1) det överensstämmer med det befintliga beteendet för överläggsportar för att helt maskera den befintliga porten, och (2) överläggsportar ger inte (och förväntas inte) ge tillräckligt med information för att driva vcpkgs versionsfunktion.

Om du vill ha flexibel portanpassning tillsammans med versionshantering bör du överväga att göra ett eget anpassat register.

Ytterligare läsning

Om du är intresserad av att fördjupa dig i information om hur versionshantering fungerar rekommenderar vi att du läser vår versionsreferens och versionsbegrepp.

  • Last updated on