Freigeben über

Erste Schritte mit der Versionsverwaltung

  • Artikel

Verwenden von Versionen mit Manifesten

Beginnen wir mit dem Erstellen eines einfachen CMake-Projekts, das von fmt und .zlib

Erstellen Sie einen Ordner mit den folgenden Dateien:

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)

Und jetzt erstellen und führen wir unser Projekt mit CMake aus:

  1. Erstellen Sie das Buildverzeichnis für das Projekt.

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

  2. Konfigurieren Sie 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. Erstellen Sie das Projekt.

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

  4. Führen Sie die App aus!

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

Sehen Sie sich die Ausgabe an:

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

Anstatt die Portdateien in ports/zu verwenden, überprüft vcpkg die Dateien für jede Version in buildtrees/versioning/versions/. Die Dateien werden ports/ weiterhin verwendet, wenn vcpkg im klassischen Modus ausgeführt wird.

Hinweis

Die Ausgabe von vcpkg beim Konfigurieren von CMake ist nur verfügbar, wenn Sie die CMake-Version 3.18 oder neuer verwenden. Wenn Sie ein älteres CMake verwenden, können Sie die vcpkg-manifest-install.log Datei stattdessen in Ihrem Buildverzeichnis überprüfen.

Lesen Sie unseren Blogbeitrag zur Manifestankündigung, um zu erfahren, wie Sie Manifeste mit MSBuild verwenden.

Manifeständerungen

Wenn Sie Manifeste verwendet haben, bevor Sie feststellen, dass es einige neue JSON-Eigenschaften gibt. Sehen wir uns diese Änderungen an:

version

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

Dies ist die Versionsdeklaration Ihres Projekts. Bisher konnten Sie nur Versionen für Ihre Projekte mit der version-string Eigenschaft deklarieren. Da sich die Versionsverwaltung nun befindet, ist vcpkg von einigen neuen Versionsverwaltungsschemas bekannt.

Versionsschema Beschreibung
version Punkttrennte Zahlen: 1.0.0.5.
version-semver Kompatible semantische Versionen: 1.2.0 und 1.2.0-rc.
version-date Datumsangaben im YYYY-MM-DD Format: 2021-01-01
version-string Beliebige Zeichenfolgen: vista, candy.

version>=

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

Diese Eigenschaft wird verwendet, um Mindestversionseinschränkungen auszudrücken, sie ist nur als Teil der "dependencies" Deklarationen zulässig. In unserem Beispiel legen wir eine explizite Einschränkung für die Version 7.1.3#1 von fmt.

vcpkg darf diese Einschränkung aktualisieren, wenn eine transitive Abhängigkeit eine neuere Version erfordert. Wenn beispielsweise zlib eine Abhängigkeit von fmt der Version 7.1.4 deklariert werden soll, würde vcpkg stattdessen installiert 7.1.4 .

vcpkg verwendet einen Minimalversionsansatz, selbst wenn fmt die Version 8.0.0 veröffentlicht werden sollte, würde vcpkg weiterhin die Version 7.1.3#1 installieren, da dies die Mindestversion ist, die die Einschränkung erfüllt. Die Vorteile dieses Ansatzes sind, dass Sie keine unerwarteten Abhängigkeitsupgrades erhalten, wenn Sie vcpkg aktualisieren und reproduzierbare Builds (in Bezug auf die verwendete Version) erhalten, solange Sie dasselbe Manifest verwenden.

Wenn Sie ihre Abhängigkeiten aktualisieren möchten, können Sie die Mindestversionseinschränkung stürzen oder einen neueren Basisplan verwenden.

builtin-baseline

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

Dieses Feld deklariert die Versionsverwaltungsbasislinie für alle Ports. Das Festlegen eines Basisplans ist erforderlich, um die Versionsverwaltung zu aktivieren, andernfalls erhalten Sie die aktuellen Versionen im ports/ Verzeichnis. Sie können "git rev-parse HEAD" ausführen, um den aktuellen Commit von vcpkg abzurufen und als integrierten Basisplan festzulegen. Weitere Informationen finden Sie in der "builtin-baseline" Dokumentation .

In unserem Beispiel deklarieren wir keine Versionsbeschränkung für zlib; stattdessen wird die Version aus der Basislinie entnommen. Intern sucht vcpkg im Commit 3426db05b996481ca31e95fff3734cf23e0f51bc , um herauszufinden, welche Version zu zlib diesem Zeitpunkt die neueste war (in unserem Fall 1.2.11#9).

Bei der Versionsauflösung werden Basisversionen als Mindestversionseinschränkungen behandelt. Wenn Sie eine explizite Einschränkung deklarieren, die niedriger als eine Basisplanversion ist, wird die explizite Einschränkung auf die Basisversion aktualisiert.

Beispiel: Wenn wir unsere Abhängigkeiten wie folgt geändert haben:

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

Hinweis

Der Wert 1.2.11#7 stellt Version 1.2.11, Portversion 7dar.

Da der Basisplan eine Mindestversionseinschränkung für zlib at und 1.2.11#9 eine höhere Version die Mindestversionseinschränkung für 1.2.11#7erfüllt, darf vcpkg sie aktualisieren.

Basispläne sind auch ein praktischer Mechanismus zum gleichzeitigen Upgrade mehrerer Versionen, z. B. wenn Sie von mehreren boost Bibliotheken abhängen möchten, ist es praktischer, die baseline einmal festzulegen, als eine Versionsbeschränkung für jedes Paket zu deklarieren.

Aber was geschieht, wenn Sie eine ältere Version als die Basislinie anheften möchten?

overrides

Da Basispläne einen Versionsboden für alle Pakete einrichten und explizite Einschränkungen aktualisiert werden, wenn sie niedriger als der Basisplan sind, benötigen wir einen weiteren Mechanismus zum Herabstufen von Versionen über den Basisplan.

Der Mechanismus vcpkg stellt dieses Szenario bereit.overrides Wenn eine Außerkraftsetzung für ein Paket deklariert wird, ignoriert vcpkg alle anderen Versionseinschränkungen entweder direkt im Manifest deklariert oder von transitiven Abhängigkeiten. Kurz gesagt overrides , erzwingt vcpkg die Verwendung der genau deklarierten Version, Punkt.

Lassen Sie uns unser Beispiel noch einmal ändern, dieses Mal, um zu erzwingen, dass vcpkg die Version 6.0.0 von fmtverwendet.

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

Erstellen Sie unser Projekt neu:

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

Und führen Sie es aus!

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

Beachten Sie, wie die fmt Version 6.0.0 jetzt wie gewünscht ist.

Versionen und benutzerdefinierte Ports

Am letzten Punkt wird erläutert, wie Überlagerungsports mit der Versionsverwaltungsauflösung interagieren. Die Antwort lautet: Sie sind nicht.

Wenn Sie eine Überlagerung für einen Port bereitstellen, verwendet vcpkg immer den Overlayport, ohne zu berücksichtigen, welche Version darin enthalten ist. Die Gründe sind zweifaltig: (1) sie ist mit dem vorhandenen Verhalten von Überlagerungsports konsistent, die den vorhandenen Port vollständig maskieren, und (2) Überlagerungsports bieten nicht (und werden nicht erwartet), um genügend Informationen bereitzustellen, um das Versionsverwaltungsfeature von vcpkg zu unterstützen.

Wenn Sie eine flexible Portanpassung zusammen mit der Versionsverwaltung haben möchten, sollten Sie ihre eigene benutzerdefinierte Registrierung erstellen.

Weitere Informationen

Wenn Sie mehr über die Funktionsweise der Versionsverwaltung erfahren möchten, empfehlen wir Ihnen, unsere Versionsverwaltungsreferenz und Versionsverwaltungskonzepte zu lesen.