Freigeben über

Registries-Konzepte

  • Artikel

Überblick

vcpkg hostet eine Auswahl von Bibliotheken, die in Ports bei https://github.com/Microsoft/vcpkgverpackt sind. Diese Portsammlung wird als kuratierte Registrierung bezeichnet. Vcpkg ist jedoch nicht auf die kuratierte Registrierung beschränkt. Benutzer können die Auswahl von Ports erweitern, indem sie benutzerdefinierte Registrierungen erstellen.

Eine Registrierung ist eine Sammlung von Ports und Hilfsdateien, die in einer bestimmten Struktur angeordnet sind. In einer Registrierung enthaltene Ports können der Registrierungsstruktur entsprechend mit den gleichen Features (Versionsverwaltung, binäres Zwischenspeichern) installiert werden wie die Ports, die in der kuratierten Registrierung für Ports verfügbar sind.

Derzeit gibt es drei Arten von Registern:

vcpkg kann angewiesen werden, Ports zu berücksichtigen, die in benutzerdefinierten Registrierungen verfügbar sind, indem eine vcpkg-configuration.json Dateiverwendet wird. Im Artikel Tutorial: Installieren einer Abhängigkeit von einer Git-basierten Registrierung erfahren Sie, wie Sie benutzerdefinierte Registrierungen in Ihren Projekten verwenden.

Registrierungsstruktur

Damit vcpkg eine Schnittstelle mit einer Registrierung herstellen kann, muss sie der folgenden Struktur entsprechen:

  • Ein Verzeichnis mit dem Namen ports enthält die Sammlung von Ports, wobei jedes Unterverzeichnis einen bestimmten Port enthält, der dem Namen des Unterverzeichnisses entspricht. Beispielsweise befinden sich die Dateien für port foo in ports/foo.
  • Ein Verzeichnis mit dem Namen versions enthält die Dateien, die die Versionsdatenbankbeinhalten.

Beispiel: Registrierungsstruktur

ports/
  foo/
    portfile.cmake
    vcpkg.json
versions/
  f-/
    foo.json
  baseline.json

Versionsdatenbank

Alle Register enthalten ein versions-Verzeichnis im Stammverzeichnis, das die -Versionsdatenbankenthält.

Es gibt zwei Komponenten für die Versionsdatenbank:

  • Die Basisdatei
  • Die Versionsdateien

Die Basisplandatei ist eine JSON-Datei namens baseline.json im Stammverzeichnis des Ordners versions.

Die Versionsdateien sind JSON-Dateien mit denselben Namen wie die verfügbaren Ports. Sie müssen bei versions/<prefix>/<port name>.jsonvorhanden sein, wobei <prefix> der erste Buchstabe des Portnamens ist, gefolgt von einem Bindestrich. Die Versionsdatei für port foo muss z. B. versions/f-/foo.jsonsein.

Der Zweck der Versionsdatei ist zweifach:

  • Auflisten aller verfügbaren Versionen der einzelnen Ports
  • Verweis auf den Speicherort, von dem die einzelnen Versionen abgerufen werden.

Das Format der Versionsdatei hängt von der Art der Registrierung ab.

Baselinedatei

Alle Register müssen unabhängig von ihrer Art eine Datei mit dem Namen baseline.json enthalten, die sich auf versions/baseline.jsonbefindet.

Der Zweck der Basisplandatei besteht darin, die Gruppe von Versionen zu beschreiben, die als neueste für alle Ports in der Registrierung gelten. Es wird erwartet, dass diese Datei jedes Mal aktualisiert wird, wenn der Registrierung eine neue Version eines Ports hinzugefügt wird.

Die Datei ist eine JSON-Datei, die aus einem einzelnen Objekt besteht, dessen Eigenschaften als Basisplanobjekte bezeichnet werden. Die Eigenschaften jedes Basisplanobjekts sind Portnamen, deren Werte Versionseinträge sind. Der im -Verzeichnis referenzierte Artikel beschreibt das Layout der Baseline-Dateien ausführlicher.

Jeder Basisversionseintrag ist ein Objekt mit den folgenden Eigenschaften:

  • baseline: der Wert ist die Portversion, die der zugehörigen vcpkg.json-Datei entspricht.
  • port-version: der Wert ist die port-version des Ports, die der zugehörigen vcpkg.json-Datei entspricht.

Beispiel-Basisdatei

{
  "default": {
    "foo": { "baseline": "1.0.0", "port-version": 0 },
    "bar": { "baseline": "2024-08-01", "port-version": 1 },
    "baz": { "baseline": "vista-xp", "port-version": 0 }
  }
}

Siehe die Referenzdokumentation für:

Versionsdateien

Jeder Port in der Registrierung verfügt über eine entsprechende Versionsdatei. Versionsdateien werden bei versions/<prefix>/<port name>.json gespeichert, wobei <prefix> der erste Buchstabe des Portnamens gefolgt von einem Bindestrich ist. Beispielsweise befindet sich die Versionsdatei für Port foo bei versions/f-/foo.json.

Der Zweck der Versionsdatei ist zweifach:

  • Auflisten aller verfügbaren Versionen der einzelnen Ports
  • Verweis auf den Speicherort, von dem jede dieser Versionen abgerufen wird

Das Layout der Versionsdatei ist ein Objekt, das ein "versions" Array enthält, wobei jeder Eintrag in diesem Array ein Versionsobjekt ist. Ein Versionsobjekt muss die folgenden Eigenschaften enthalten:

  • Eine Versions-Eigenschaft: Der Schlüssel und der Wert der Eigenschaft müssen mit denen übereinstimmen, die vom Port in der vcpkg.json-Datei verwendet werden. Der Schlüssel muss einer von version, version-semver, version-dateoder version-stringsein; der Wert muss die Version sein, wie er in der Manifestdatei des Ports angezeigt wird (vcpkg.json).
  • port-version: Der Wert ist die port-version des Ports, wie sie in dessen vcpkg.json-Datei angezeigt wird.
  • git-tree: (nur für Git-Registrierungen) der Wert ist der Git-Struktur-SHA, der dem Portverzeichnis entspricht. Dies ist ein SHA, der durch das Hashing des Inhalts des Port-Verzeichnisses berechnet wird; dieser Git-Tree-SHA kann von Git verwendet werden, um den Inhalt des Ports abzurufen, der der bereitgestellten Git-Struktur entspricht. Dies ermöglicht es vcpkg, alte Versionen von Ports aus dem Git-Verlauf der Registrierungen abzurufen. Lesen Sie die Git-Registrierungen Abschnitt, um zu erfahren, wie Sie diesen Wert für eine bestimmte Portversion abrufen.
  • path: (nur bei Dateisystemregistrierungen) ist der Wert der vollständige Pfad zu einem Verzeichnis, das die Portdateien für die jeweilige Version enthält.

Beispiel für eine Dateisystemregistrierungsversionsdatei

{
  "versions": [
    {
      "path": "$/ports/foo/1.2.0",
      "version": "1.2.0",
      "port-version": 0
    },
    {
      "path": "$/ports/foo/1.1.0",
      "version": "1.1.0",
      "port-version": 0
    },
    {
      "path": "$/ports/foo/1.0.0",
      "version": "1.0.0",
      "port-version": 0
    }
  ]
}

Siehe die Referenzdokumentation für:

Integrierte Registrierung

Das eingebaute Register ist eine spezielle Art von Register. Es ist die Standardregistrierung, die im klassischen Modus verwendet wird. Im Manifestmodus verwendet vcpkg die integrierte Registrierung implizit, wenn keine Standardregistrierung angegeben ist.

Die integrierte Registrierung bezieht sich auf die lokale Kopie der kuratierten Registrierung, die erstellt wurde, als Sie ein git clone der vcpkg-Registrierung über https://github.com/Microsoft/vcpkg vorgenommen haben. Einige Vorgänge erwarten, dass die VCPKG_ROOT Umgebungsvariable auf eine integrierte Registrierung verweist.

Wenn vcpkg über das Installationsprogramm "one liner" oder Visual Studio erworben wird, entspricht die integrierte Registrierung einer Git-Registrierung, die auf das https://github.com/Microsoft/vcpkg Repository verweist.

Git-Registrierungen

Eine Git-Registrierung ist ein Repository, das der Registrierungsstruktur folgt und die Funktionen von Git nutzt, um die Versionsverwaltung für die Ports in der Registrierung bereitzustellen. Die kuratierte Registrierung bei https://github.com/Microsoft/vcpkg ist eine Implementierung einer Git-Registrierung.

Git-Registrierungen können in einem beliebigen Git-Repositoryanbieter gehostet werden, sodass Sie Ihren ausgewählten Git-Hostingdienst verwenden können, um den Zugriff auf Ihre benutzerdefinierte Registrierung zu steuern und gleichzeitig ihre Registrierung einfach freizugeben.

Git-Registrierungen sind die empfohlene Methode für die Implementierung einer benutzerdefinierten Registrierung. Da der Versionsverwaltungsmechanismus identisch ist, der von der kuratierten Registrierung verwendet wird, können Git-Registrierungen die x-add-version verwenden, um Ihre Versionsdatenbankdateien zu verwalten.

Weitere Informationen zur Implementierung von Git-Registrierungen finden Sie in der Referenz zu Registrierungen.

Hinzufügen einer neuen Version zu einer Git-Registrierung

Der Befehl x-add-version kann verwendet werden, um der Registrierung einen neuen Port oder eine neue Version hinzuzufügen. Beim Hinzufügen von Versionen mit diesem Befehl gibt es einige Dinge, die Sie berücksichtigen sollten:

Wichtig

Denken Sie beim Hinzufügen einer neuen Version immer daran, die deklarierte Version des Ports auf eine version zu aktualisieren, die noch nicht veröffentlicht wurde, um das Umschreiben des Versionsverlaufs zu vermeiden.

Wenn Sie Änderungen an einem Port vornehmen, sollte der erste Schritt darin bestehen, die Version in der vcpkg.json Datei zu erhöhen. Wenn Ihre Änderungen ein Update auf die upstream- Version des Pakets enthalten, denken Sie daran, die port-version auf 0festzulegen; andernfalls denken Sie daran, die port-version um eins zu erhöhen.

Der x-add-version Befehl erfordert, dass alle Portänderungen vor dem Aktualisieren der Versionsdatenbank an das Repository übertragen werden.

Beispiel: Hinzufügen einer neuen Portversion zu einer Git-Registrierung

git add ports/foo/.
git commit -m "Temporary commit"
vcpkg x-add-version --x-builtin-ports-root=./ports --x-builtin-registry-versions-dir=./versions foo
added version 1.0.0#1 to path/to/registry/versions/f-/foo.json
added version 1.0.0#1 to path/to/registry/versions/baseline.json

Die Umleitungsoptionen --x-builtin-ports-root und --x-builtin-registry-versions-dir sollten auf Ihre Registry-ports- und versions-Verzeichnisse verweisen.

Sobald der Befehl x-add-version erfolgreich ausgeführt wird, ändern Sie den letzten Commit, um die Versionsdateiänderungen einzuschließen.

git commit --amend -m "Update foo to new version"

Dateisystemregistrierungen

Dateisystemregistrierungen sind eine Implementierung einer Registrierung, die sich auf einem Dateisystem befindet. Sie folgen der gemeinsamen Registrierungsstruktur, verwenden jedoch nicht Git, um Versionsverwaltungsfunktionen anzubieten. Stattdessen verwenden sie eine primitive Form des Versionssteuerelements mit einem eindeutigen Pfad für jede Version ihrer Ports.

Diese Art von Registrierung eignet sich für einen Testplatz für Ihre Ports oder um eine Alternative für eine Registrierung in einem Nicht-Git-Versionskontrollsystem bereitzustellen. Dateisystemregistrierungen werden für eine große Sammlung von Ports nicht empfohlen, und es wird kein Tool zum Bearbeiten der Versionsdatenbankdateien für diese Art von Registrierung bereitgestellt.

Weitere Informationen zum Implementieren einer Dateisystemregistrierung finden Sie in der Registrierungsreferenz.

Nutzen von Registrierungen

Um eine benutzerdefinierte Registrierung in Ihrem Projekt zu nutzen, müssen Sie eine Konfigurationsdatei (vcpkg-configuration.json) neben der Manifestdatei (vcpkg.json) Ihres Projektserstellen.

Standardregistrierung

Beim Auflösen von Portnamen dient die Standardregistrierung als Fallback, wenn der Name eines Ports keinem der Paketmuster entspricht, die von anderen Registrierungen im registries-Array deklariert wurden.

Zur Vereinfachung für Benutzer, die keine benutzerdefinierten Registries verwenden, fügt vcpkg implizit die eingebaute Registry als Standardregistry hinzu. Um dieses Verhalten zu ändern, kann die Standardregistrierung auf eine beliebige Registrierung festgelegt oder vollständig deaktiviert werden. default-registry-Eigenschaft.

Beispiel: Festlegen einer benutzerdefinierten Registrierung als Standard

vcpkg-configuration.json

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/Microsoft/vcpkg",
    "baseline": "84a143e4caf6b70db57f28d04c41df4a85c480fa"
  }
}

Beispiel: Deaktivieren der Standardregistrierung

vcpkg-configuration.json

{
  "default-registry": null
}

Registries-Array

Um die Auswahl der ports zu erweitern, die für die Installation mit vcpkg verfügbar sind, können Sie zusätzliche Registrierungen mithilfe des registries Arraysangeben.

Beispiel: Hinzufügen von benutzerdefinierten Registrierungen zur Konfiguration

Anmerkung

Je nach Registrierungsart müssen Sie möglicherweise unterschiedliche Informationen im registries Array angeben. In der vcpkg-configurtion.json Referenz erfahren Sie, welche Eigenschaften für jede Registrierungsart erforderlich sind.

vcpkg-configuration.json

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/Microsoft/vcpkg",
    "baseline": "84a143e4caf6b70db57f28d04c41df4a85c480fa"
  },
  "registries": [
    {
      "kind": "git",
      "repository": "https://my.privateregistry.git",
      "baseline": "caf6b70db5784a143e4f28d05c480fa4c41df4a8",
      "packages": [ "foo" ]
    },
    {
      "kind": "filesystem",
      "path": "C:/path/to/registry",
      "baseline": "baseline1",
      "packages": [ "bar" ]
    }
  ]
}

Versionsverlauf nicht neu schreiben

Nachdem eine Version in den Versionsdateien veröffentlicht wurde, ändern Sie die zugeordnete git-tree-Nummer nicht in einem Git-Repository oder einem Verzeichnis im Dateisystem.

Eine der Designprinzipien von vcpkg besteht darin, dass sich die Versionen installierter Abhängigkeiten ohne Benutzereingriff nicht ändern. Das Umschreiben des Versionsdateiverlaufs durch Ändern eines git-tree Eintrags verstößt gegen dieses Prinzip.

Wenn die vorhandene Version Probleme hat, sollten Sie lieber eine neue port-versionerstellen.

Versionsdateien nicht löschen

Anmerkung

Dieser Abschnitt gilt nur für Git-Registrierungen

Wenn Sie einen Port aus Ihrer Registrierung entfernen, entfernen Sie den Inhalt aus dem Portsverzeichnis und dessen Eintrag in der Basisplandatei. Entfernen Sie jedoch nicht die zugehörige Versionsdatei.

Auch wenn in der Registrierung kein Port mehr vorhanden ist, solange die Versionsdatei bleibt, können Benutzer des Ports alte Versionen mithilfe Version overridesinstallieren.

Nächste Schritte

Hier sind einige Aufgaben, die Sie als Nächstes ausprobieren können: