Registries-Konzepte
Ü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 portfoo
inports/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>.json
vorhanden 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.json
sein.
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.json
befindet.
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örigenvcpkg.json
-Datei entspricht. -
port-version
: der Wert ist dieport-version
des Ports, die der zugehörigenvcpkg.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:
- Layout der Baselinedatei für Git-Registrierungen
- Layout der Baselinedatei für Dateisystemregistrierungen
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 vonversion
,version-semver
,version-date
oderversion-string
sein; der Wert muss die Version sein, wie er in der Manifestdatei des Ports angezeigt wird (vcpkg.json
). port-version
: Der Wert ist dieport-version
des Ports, wie sie in dessenvcpkg.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:
- Layout der Versionsdatei für Git-Registrierungen
- Layout der Versionsdatei für Dateisystemregistrierungen
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 0
festzulegen; 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" ]
}
]
}
Empfohlene Methoden für Registrierungen
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-version
erstellen.
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 overrides
installieren.
Nächste Schritte
Hier sind einige Aufgaben, die Sie als Nächstes ausprobieren können: