Handbuch zur Problembehandlung bei der Versionsverwaltung

Artikel
02/10/2025

Dieses Handbuch richtet sich an Benutzer, die Probleme mit der Versionierunghaben.

Überprüfen der Versionsdatei für einen Port

Anmerkung

Der unten beschriebene Prozess soll für Ports aus der vcpkg-Registrierung funktionieren. In unserer Register Dokumentation erfahren Sie, wie die Versionsdatenbank in benutzerdefinierten Registern implementiert wird.

So prüfen Sie die Versionsdatenbank eines bestimmten Ports:

Navigieren Sie zum verzeichnis vcpkg/versions.
Suchen Sie den Ordner des Ports:
- Suchen Sie den Ordner, der dem ersten Buchstaben des Ports entspricht. Zum Beispiel, öffnen Sie für fmt den Ordner mit dem Namen f-.
Öffnen Sie die Portversionsdatei:
- Suchen Sie die JSON-Datei mit demselben Namen des Ports. Die fmt Versionsdatei heißt z. B. fmt.json.

Die Versionsdatei des Ports enthält eine Liste der verfügbaren Versionen mit Details wie Versionstags und den entsprechenden Git-Strukturobjekthash. Diese Informationen werden von vcpkg benötigt, um bestimmte Portversionen abzurufen. Es stehen nur Versionen in dieser Liste zur Verfügung, die in Ihren Manifestdateien verwendet werden können.

Weitere Informationen zur Versionsverwaltung finden Sie in unserer Referenzdokumentation:

Weitere Informationen zur Verwendung eines Manifests finden Sie unter Manifest-

Ursache: Anfordern einer nicht vorhandenen Version eines Pakets

Wenn eine in der Manifestdatei angegebene Version in der vcpkg-Versionsdatenbank nicht vorhanden ist, kann vcpkg die Abhängigkeit nicht beheben und eine Fehlermeldung wie folgt erzeugt:

error: no version database entry for fmt at 100.0.0
Available versions:
  10.1.1
  10.1.0
  10.0.0
  9.1.0#1
  9.1.0
  9.0.0
  8.1.1#2
  8.1.1#1
  ...
See `vcpkg help versioning` or https://learn.microsoft.com/vcpkg/users/versioning for more information.

So beheben Sie das Problem:

Aktualisieren sie die Versionsdatenbank:
- Die gewünschte Version ist möglicherweise nicht in Ihrer lokalen Kopie der Versionsdatenbank enthalten. Führen Sie in diesem Fall den Befehl git pull aus, um die vcpkg-Registrierung auf den neuesten Commit zu aktualisieren.
Verfügbare Versionen überprüfen:
- Wählen Sie eine der in der Versionsdatenbank verfügbaren Versionen aus.
Manifestdatei aktualisieren:
- Bearbeiten Sie Ihre vcpkg.json Datei.
- Ändern Sie die angegebene Version in eine Version, die im vcpkg-Repository verfügbar ist. Ändern Sie z. B. von "version>=": "100.0.0" in "version>=": "10.1.1".
Ausführen der vcpkg-Installation:
- Führen Sie den befehl vcpkg install erneut in Ihrem Terminal oder an der Eingabeaufforderung aus.

Ursache: Angeben der Versionseinschränkung in verschiedenen Schemas

Ein Versionsschemakonflikt tritt auf, wenn die in der vcpkg.json-Datei für eine Abhängigkeit angegebene Version ein anderes Versionsverwaltungsschema verwendet als das, das in der Basisversion des vcpkg-Repositorys verwendet wird. Dies führt zu einem Fehler, da vcpkg Versionen nicht in verschiedenen Schemas vergleichen kann.

Wenn eine deklarierte version>= Einschränkung ein anderes Versionsschema als das in der Basisplanversion verwendete verwendet, kann vcpkg nicht ermitteln, welche Version größer oder gleich dem anderen ist.

Wenn Sie beispielsweise Folgendes angeben:

{
  "dependencies": [
    {
      "name": "boost-regex",
      "version>=": "1.75.0"
    }
  ]
}

vcpkg gibt die folgende Fehlermeldung aus:

error: version conflict on boost-regex:x64-windows:  required 1.75.0, which cannot be compared with the baseline version 1.83.0.

The versions have incomparable schemes:
  boost-regex@1.83.0 has scheme relaxed
  boost-regex@1.75.0 has scheme string

This can be resolved by adding an explicit override to the preferred version. For example:

  "overrides": [
    { "name": "boost-regex", "version": "1.83.0" }
  ]

See `vcpkg help versioning` or https://learn.microsoft.com/vcpkg/users/versioning for more information.

Resolutionen:

Verwenden Sie ein kompatibles Versionsschema:
- Überprüfen Sie die Versionsdatenbank im vcpkg-Repository unter versions/b-/boost-regex.json, um eine Version von boost-regex zu finden, die das gleiche Versionsverwaltungsschema wie der Basisplan verwendet.
- Aktualisieren Sie die version>= Einschränkung in Ihrem vcpkg.json auf eine Version, die ein kompatibles Schema verwendet.
Überschreiben der gewünschten Version:
- Wenn Sie eine bestimmte Version von Boost-regex benötigen, die ein anderes Versionsverwaltungsschema verwendet, können Sie es in Ihrem Manifest überschreiben.
- Ändern Sie Ihre vcpkg.json, um einen Bereich für Überschreibungen einzuschließen, in dem die gewünschte Version angegeben wird:
```
{
  "dependencies": [
    { "name": "boost-regex" }
  ],
  "overrides": [
    { "name": "boost-regex", "version": "1.75.0" }
  ]
}
```

Ursache: Unzureichender Commitverlauf im flachen Klon

Wenn vcpkg mit einem begrenzten Commitverlauf geklont wird (flacher Klon), fehlt ihm der erforderliche Commitverlauf, um bestimmte Versionsbeschränkungen oder Basispläne aufzulösen. Die Hashes des Git-Strukturobjekts, die vcpkg zum Abrufen bestimmter Portversionen verwendet, sind nur dann verfügbar, wenn der vollständige Commitverlauf ausgecheckt ist. vcpkg erkennt, wenn er in ein flaches Repository geklont wurde, und generiert eine Fehlermeldung, wenn keine Portversion abgerufen werden kann.

Die Verwendung von vcpkg.json mit einer spezifischen, im Folgenden aufgeführten Baseline:

{
  "dependencies": [
    {
      "name": "fmt"
    }
  ],
  "overrides": [
    {
      "name": "fmt",
      "version": "7.1.3#1"
    }
  ],
  "builtin-baseline": "bb588985e37484d543fc849d0d79434e0d45bb3c"
}

Führt zu folgendem Fehler:

error: failed to execute: "C:\Program Files\Git\cmd\git.exe" "--git-dir=C:\dev\demo\vcpkg\.git" "--work-tree=C:\dev\demo\vcpkg\buildtrees\versioning_\versions\fmt\4f8427eb0bd40da1856d4e67bde39a4fda689d72_26648.tmp" -c core.autocrlf=false read-tree -m -u 4f8427eb0bd40da1856d4e67bde39a4fda689d72
vcpkg was cloned as a shallow repository in: C:\dev\demo\vcpkg\.git
Try again with a full vcpkg clone.
error: git failed with exit code: (128).
fatal: failed to unpack tree object 4f8427eb0bd40da1856d4e67bde39a4fda689d72
note: while checking out port fmt with git tree 4f8427eb0bd40da1856d4e67bde39a4fda689d72

Dieser Fehler weist darauf hin, dass der Commit (4f8427eb0bd40da1856d4e67bde39a4fda689d72), der für die spezifische Version des Pakets fmt erforderlich ist, im flachen Klon nicht verfügbar ist.

Resolutionen:

Konvertieren in einen vollständigen Klon
- Die einfachste Lösung für dieses Problem besteht darin, in den vollständigen Klon zu konvertieren:
```
git fetch --unshallow
```
Verwenden von GitHub-Aktionen (Standardmäßig auf flachen Klonen)
- GitHub Actions verwendet häufig standardmäßig flache Klone. Um dies zu umgehen, können Sie den GitHub-Aktionsworkflow so ändern, dass ein vollständiger Klon ausgeführt wird. Fügen Sie den folgenden Schritt hinzu, bevor Sie vcpkg verwenden:
```
- name: Convert to Full Clone
  run: git fetch --unshallow
```

Ursache: Unerwartete Einbeziehung von Standardfunktionen in transitive Abhängigkeiten

Beim Verwalten von Abhängigkeiten mit vcpkg stellen Sie möglicherweise fest, dass transitive Abhängigkeiten mit ihren Standardfeatures installiert werden, auch wenn Sie diese Features für Ihr Projekt möglicherweise nicht benötigen. Diese Situation kann zu einer unerwarteten Aufblähung oder Funktionalität in Ihrem finalen Build führen.

Szenario

Sie haben eine Abhängigkeit auf Bibliothek Y, die wiederum von Bibliothek Xabhängig ist. Bibliotheks-X verfügt über Standardfeatures, einschließlich foo, die Sie von Ihrem Projekt ausschließen möchten. Ihr oberstes Manifest für Bibliothek Y könnte etwa wie folgt aussehen:

{
  "name": "my-project",
  "dependencies": [
    {
      "name": "Y",
      "features": ["featureB"],
      "default-features": false
    }
  ]
}

Sie erwarten, dass X aufgrund der "default-features": false Einstellung ohne die Standardfeatures installiert wird. X wird jedoch weiterhin mit dem Standard-Feature fooinstalliert.

Grund

Die default-features-Eigenschaft wird nur im Manifest auf oberster Ebene berücksichtigt. Dies bedeutet, dass Standardfunktionen von transitiven Abhängigkeiten (z. B. X in diesem Szenario) weiterhin einbezogen werden, es sei denn, sie sind explizit auf oberster Ebene ausgeschaltet. Wenn Bibliothek Y aufgelöst wird, vererbt vcpkg die "default-features": false Einstellung nicht an die transitive Abhängigkeit X, was dazu führt, dass X mit seinen Standardfunktionen installiert wird.

Lösung

Um sicherzustellen, dass transitive Abhängigkeiten wie X ohne ihre Standardfeatures installiert werden, müssen Sie sie in Ihrem Manifest der oberen Ebene als direkte Abhängigkeiten angeben und ihre Standardfeatures explizit deaktivieren. Ändern Sie Ihre vcpkg.json, um X direkt mit "default-features": falseeinzuschließen.

{
  "name": "my-project",
  "dependencies": [
    {
      "name": "Y",
      "features": ["featureB"]
    },
    {
      "name": "X",
      "default-features": false
    }
  ]
}

Mit diesem Ansatz wird sichergestellt, dass X ohne standardfeatures installiert wird, da X jetzt eine direkte Abhängigkeit mit einer expliziten Anweisung zum Ausschließen von Standardfeatures ist.

Ausführlichere Informationen zur Funktionsweise von Standardfeatures und deren Verwaltung finden Sie im Konzeptartikel Standardfeatures Artikel.

Das Problem ist hier nicht aufgeführt.

Wenn Ihr Problem hier nicht aufgeführt ist, besuchen Sie unser Repository, um ein neues Problem zu erstellen.

Freigeben über