Aan de slag met versiebeheer

Artikel
01/10/2024

Versies met manifesten gebruiken

Laten we beginnen met het maken van een eenvoudig CMake-project dat afhankelijk is van fmt en zlib.

Maak een map met de volgende bestanden:

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)

En nu bouwen en voeren we ons project uit met CMake:

Maak de buildmap voor het project.

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

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

Bouw het project.

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

Voer het uit!

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

Bekijk de uitvoer:

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

In plaats van de portfiles in ports/te gebruiken, checkt vcpkg de bestanden voor elke versie in buildtrees/versioning/versions/uit. De bestanden in ports/ worden nog steeds gebruikt bij het uitvoeren van vcpkg in de klassieke modus.

Notitie

Uitvoer van vcpkg tijdens het configureren van CMake is alleen beschikbaar wanneer u CMake-versie 3.18 of hoger gebruikt. Als u een oudere CMake gebruikt, kunt u in plaats daarvan het vcpkg-manifest-install.log bestand controleren in uw buildmap.

Lees onze blogpost manifesten voor meer informatie over het gebruik van manifesten met MSBuild.

Manifestwijzigingen

Als u manifesten hebt gebruikt voordat u merkt dat er enkele nieuwe JSON-eigenschappen zijn. Laten we deze wijzigingen eens bekijken:

`version`

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

Dit is de versiedeclaratie van uw project. Voorheen kon u alleen versies voor uw projecten declareren met behulp van de eigenschap version-string. Nu versiebeheer is gekomen, is vcpkg op de hoogte van enkele nieuwe versiebeheerschema's.

Versieschema	Beschrijving
`version`	Door puntjes gescheiden numerieke waarden: `1.0.0.5`.
`version-semver`	Compatibele semantische versies: `1.2.0` en `1.2.0-rc`.
`version-date`	Datums in `YYYY-MM-DD` indeling: `2021-01-01`
`version-string`	Willekeurige tekenreeksen: `vista`, `candy`.

`version>=`

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

Deze eigenschap wordt gebruikt om minimale versiebeperkingen uit te drukken. Deze eigenschap is alleen toegestaan als onderdeel van de declaraties van "dependencies". In ons voorbeeld stellen we een expliciete beperking in voor versie 7.1.3#1 van fmt.

vcpkg mag deze beperking upgraden als voor een transitieve afhankelijkheid een nieuwere versie is vereist. Als zlib bijvoorbeeld een afhankelijkheid van fmt versie 7.1.4 zou declareren, installeert vcpkg in plaats daarvan 7.1.4.

vcpkg maakt gebruik van een minimale versiebenadering, zelfs als fmt versie 8.0.0 zou worden uitgebracht, zou vcpkg versie nog steeds installeren 7.1.3#1 omdat dat de minimale versie is die voldoet aan de beperking. De voordelen van deze aanpak zijn dat u geen onverwachte afhankelijkheidsupgrades krijgt wanneer u vcpkg bijwerkt en u reproduceerbare builds krijgt (wat betreft de gebruikte versie) zolang u hetzelfde manifest gebruikt.

Als u uw afhankelijkheden wilt upgraden, kunt u de minimale versiebeperking stoten of een nieuwere basislijn gebruiken.

`builtin-baseline`

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

Dit veld declareert de basislijn voor versiebeheer voor alle poorten. Het instellen van een basislijn is vereist om versiebeheer in te schakelen, anders krijgt u de huidige versies in de ports/ map. U kunt 'git rev-parse HEAD' uitvoeren om de huidige doorvoer van vcpkg op te halen en in te stellen als de ingebouwde basislijn. Zie de "builtin-baseline" documentatie voor meer informatie.

In ons voorbeeld declareren we geen versiebeperking voor zlib; In plaats daarvan wordt de versie uit de basislijn gehaald. Intern zal vcpkg in commit 3426db05b996481ca31e95fff3734cf23e0f51bc kijken om erachter te komen welke versie van zlib de laatste was op dat moment (in ons geval was het 1.2.11#9).

Tijdens versieomzetting worden basislijnversies behandeld als minimale versiebeperkingen. Als u een expliciete beperking declareert die lager is dan een basislijnversie, wordt de expliciete beperking bijgewerkt naar de basislijnversie.

Als we bijvoorbeeld onze afhankelijkheden als volgt hebben gewijzigd:

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

Notitie

De waarde 1.2.11#7 staat voor versie 1.2.11, poortversie 7.

Omdat de basislijn een minimale versiebeperking introduceert voor zlib op 1.2.11#9 en een hogere versie voldoet aan de minimale versiebeperking voor 1.2.11#7, mag vcpkg deze upgraden.

Basislijnen zijn ook een handig mechanisme om meerdere versies tegelijk bij te werken, bijvoorbeeld als u afhankelijk wilt zijn van meerdere boost bibliotheken, is het handiger om de baseline eenmaal in te stellen dan het declareren van een versiebeperking voor elk pakket.

Maar wat als u een versie wilt vastmaken die ouder is dan de basislijn?

`overrides`

Omdat basislijnen een versievloer voor alle pakketten en expliciete beperkingen tot stand brengen wanneer ze lager zijn dan de basislijn, hebben we een ander mechanisme nodig om versies te downgraden voorbij de basislijn.

Het mechanisme vcpkg voorziet in dat scenario is overrides. Wanneer een onderdrukking wordt gedeclareerd voor een pakket, negeert vcpkg alle andere versiebeperkingen, hetzij rechtstreeks gedeclareerd in het manifest of van transitieve afhankelijkheden. Kortom, overrides dwingt vcpkg om de exacte versie te gebruiken die is gedeclareerd, punt.

We gaan ons voorbeeld nogmaals wijzigen, deze keer om vcpkg af te dwingen versie 6.0.0 van fmtte gebruiken.

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

Bouw ons project opnieuw op:

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

En voer het uit!

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

U ziet dat de fmt nu versie 6.0.0 net zoals we wilden.

Versies en aangepaste poorten

Het laatste wat u moet bespreken, is hoe overlaypoorten communiceren met versiebeheerresolutie. Het antwoord is dat ze dat niet doen.

Als u een overlay voor een poort opgeeft, gebruikt vcpkg altijd de overlaypoort zonder te zorgen welke versie erin is opgenomen. De redenen zijn tweevoudig: (1) het is consistent met het bestaande gedrag van overlaypoorten voor het volledig maskeren van de bestaande poort en (2) overlaypoorten bieden niet (en worden niet verwacht) voldoende informatie te bieden voor de versiebeheerfunctie van vcpkg.

Als u flexibele poortaanpassing wilt hebben in combinatie met versiebeheer, moet u overwegen uw eigen aangepaste registerte maken.

Meer lezen

Als u meer wilt weten over de werking van versiebeheer, raden we u aan onze Versieverwijzing en versiebeheerconceptente lezen.

Delen via