Erstellen von Registrierungen

Informationen zum Verbrauch von Registern finden Sie unter Verwendung von Registern.

Übersicht

Registrierungen sind Sammlungen von Ports und deren Versionen. Es gibt zwei wichtige Auswahlmöglichkeiten für die Implementierung von Registrierungen, wenn Sie eigene erstellen möchten: Git-Registrierungen und Dateisystemregistrierungen.

Git-Registrierungen sind einfache Git-Repositorys und können öffentlich oder privat über normale Mechanismen für Git-Repositorys freigegeben werden. Das vcpkg-Repository ist z. B. eine Git-Registrierung.

Filesystemregistries sind als mehr Testplatz konzipiert. Da sie buchstäblich in Ihrem Dateisystem leben, ist die einzige Möglichkeit, sie freizugeben, über freigegebene Verzeichnisse. Dateisystemregistrierungen können jedoch hilfreich sein, um Registrierungen darzustellen, die in Nicht-Git-Versionskontrollsystemen gespeichert sind, vorausgesetzt, dass man eine Möglichkeit hat, die Registrierung auf den Datenträger zu übertragen.

Wir erwarten, dass die Reihe von Registrierungstypen im Laufe der Zeit wachsen wird; Wenn Sie Unterstützung für Registrierungen wünschen, die in Ihrem bevorzugten öffentlichen Versionskontrollsystem integriert sind, zögern Sie nicht, eine PR zu öffnen.

Die grundlegende Struktur einer Registrierung lautet:

• Die Gruppe von Versionen, die zu bestimmten Zeiten im Verlauf als "neueste" betrachtet werden, die als "Basisplan" bezeichnet werden.
• Die Gruppe aller Versionen aller Ports und deren Speicherort in der Registrierung.

Git-Registrierungen

Wenn Sie zusammen mit dieser Dokumentation folgen, kann es hilfreich sein, ein funktionierendes Beispiel zu verwenden, auf das Verwiesen wird. Wir haben eins geschrieben und hier abgelegt:

Microsoft/vcpkg-docs: vcpkg registry.

Alle Git-Registrierungen müssen über eine versions/baseline.json Datei verfügen. Diese Datei enthält den Satz der "neuesten Versionen" bei einem bestimmten Commit. Es ist als Objekt der obersten Ebene angeordnet, das nur das "default" Feld enthält. Dieses Feld sollte einen Objektzuordnungsportnamen zu der Version enthalten, die derzeit die neueste ist.

Hier ist ein Beispiel für eine gültige baseline.json:

{
  "default": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  }
}

Das versions Verzeichnis enthält alle Informationen darüber, welche Versionen von welchen Paketen in der Registrierung enthalten sind, zusammen mit dem Speicherort dieser Versionen. Der Rest der Registrierung fungiert nur als Sicherungsspeicher, was vcpkg betrifft: Nur Dinge innerhalb des versions Verzeichnisses werden verwendet, um zu leiten, wie Ihre Registrierung von vcpkg gesehen wird.

Jeder Port in einer Registrierung sollte im Versionsverzeichnis vorhanden sein, d <first letter of port>-/<name of port>.json. h., die Informationen zum kitten Port befinden sich in versions/k-/kitten.json. Dies sollte ein Objekt der obersten Ebene mit nur einem einzigen Feld sein: "versions". Dieses Feld sollte ein Array von Versionsobjekten enthalten:

• Die betreffende Portversion; sollte genau mit der vcpkg.json Datei identisch sein, einschließlich der Versionsfelder und "port-version".
• Das "git-tree" Feld, bei dem es sich um eine Git-Struktur handelt; mit anderen Worten, was Sie beim Schreiben git rev-parse COMMIT-ID:path/to/porterhalten.

Das Versionsfeld für Ports mit veralteten CONTROL Dateien ist "version-string".

Warnung

Ein sehr wichtiger Bestandteil der Registrierungen ist, dass Versionen niemals geändert werden sollten. Das Aktualisieren auf eine spätere Referenz sollte niemals eine vorhandene Version entfernen oder ändern. Es muss immer sicher sein, eine Registrierung zu aktualisieren.

Hier ist ein Beispiel für eine gültige Versionsdatenbank für einen kitten Port mit einer Version:

{
  "versions": [
    {
      "version": "2.6.2",
      "port-version": 0,
      "git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e"
    }
  ]
}

Im Allgemeinen ist es nicht wichtig, wo Sie Portverzeichnisse platzieren. Der Idiom in vcpkg folgt jedoch dem, was die integrierte vcpkg-Registrierung bewirkt: Ihr kitten Port sollte in ports/kitten.

Warnung

Ein weiterer Aspekt ist, dass beim Aktualisieren einer Registrierung auch auf alle früheren Versionen zugegriffen werden sollte. Da Der Benutzer seinen Basisplan auf eine Commit-ID festlegt, muss diese Commit-ID immer vorhanden sein und von Ihrem HEAD-Commit aus zugänglich sein, was tatsächlich abgerufen wird. Dies bedeutet, dass Ihr HEAD Commit ein Kind aller vorherigen HEAD Commits sein sollte.

Integrierte Registrierungen

Integrierte Registrierungen werden als spezielle Git-Registrierungen behandelt. Anstatt von einer Remote-URL abzurufen, konsultieren integrierte Registrierungen das $VCPKG_ROOT/.git Verzeichnis des vcpkg-Klons. Sie verwenden das aktuell ausgecheckte $VCPKG_ROOT/versions Verzeichnis als Quelle für Versionsverwaltungsinformationen.

Hinzufügen einer neuen Version

Es gibt einige Git-Tricks, die an der Erstellung einer neuen Version eines Ports beteiligt sind. Als Erstes müssen Sie einige Änderungen vornehmen, das Feld für die "port-version" normale Version entsprechend aktualisieren und dann mit overlay-ports:

vcpkg install kitten --overlay-ports=ports/kitten.

Nachdem Sie Ihre Tests abgeschlossen haben, müssen Sie sicherstellen, dass das Verzeichnis, wie es sich in der reinen Ansicht von Git befindet, befindet. Dazu erstellen Sie einen temporären Commit:

> git add ports/kitten
> git commit -m 'temporary commit'

Rufen Sie dann die Git-Struktur-ID des Verzeichnisses ab:

> git rev-parse HEAD:ports/kitten
73ad3c823ef701c37421b450a34271d6beaf7b07

Anschließend können Sie diese Version der Versionsdatenbank hinzufügen. Oben in Ihrem versions/k-/kitten.jsonAddieren können Sie (vorausgesetzt, Sie fügen die Version 2.6.3#0hinzu):

{
  "versions": [
    {
      "version": "2.6.3",
      "port-version": 0,
      "git-tree": "73ad3c823ef701c37421b450a34271d6beaf7b07"
    },
    {
      "version": "2.6.2",
      "port-version": 0,
      "git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e"
    }
  ]
}

Anschließend möchten Sie Auch Ihre versions/baseline.json neue Version ändern:

{
  "default": {
    "kitten": {
      "baseline": "2.6.3",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  }
}

und ändern Sie Ihren aktuellen Commit:

> git commit --amend

dann teilen!

Dateisystemregistrierungen

Wenn Sie zusammen mit dieser Dokumentation folgen, kann es hilfreich sein, ein funktionierendes Beispiel zu verwenden, auf das Verwiesen wird. Wir haben eins geschrieben und hier abgelegt:

Beispiel für die Dateisystemregistrierung.

Alle Dateisystemregistrierungen müssen über eine versions/baseline.json Datei verfügen. Diese Datei enthält den Satz der "neuesten Versionen" für eine bestimmte Version der Registrierung. Es wird als Objekt auf oberster Ebene mit einer Zuordnung von Versionsnamen zu "Basisobjekten" angelegt, die Portnamen der Version zuordnen, die als "neueste" für diese Version der Registrierung betrachtet wird.

Dateisystemregistrierungen müssen sich für ein Versionsverwaltungsschema entscheiden. Im Gegensatz zu Git-Registries, die über das implizite Versionsverwaltungsschema von Refs verfügen, können Dateisystemregistrierungen hier nicht auf das Versionskontrollsystem angewiesen werden. Eine mögliche Option besteht darin, eine tägliche Veröffentlichung durchzuführen und ihre "Versionen" als Datumsangaben festzulegen.

Warnung

Ein Basisplan darf nach der Veröffentlichung nicht mehr geändert werden. Wenn Sie Versionen ändern oder aktualisieren möchten, müssen Sie einen neuen Basisplan in der baseline.json Datei erstellen.

Hier ist ein Beispiel für ein gültiges baseline.json, für eine Registrierung, die datumsbasierte Datumsangaben für ihre Versionen festgelegt hat:

{
  "2021-04-16": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  },
  "2021-04-15": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 1
    }
  }
}

Das versions Verzeichnis enthält alle Informationen darüber, welche Versionen von welchen Paketen in der Registrierung enthalten sind, zusammen mit dem Speicherort dieser Versionen. Der Rest der Registrierung fungiert nur als Sicherungsspeicher, was vcpkg betrifft: Nur Dinge innerhalb des versions Verzeichnisses werden verwendet, um zu leiten, wie Ihre Registrierung von vcpkg gesehen wird.

Jeder Port in einer Registrierung sollte im Versionsverzeichnis vorhanden sein, d <first letter of port>-/<name of port>.json. h., die Informationen zum kitten Port befinden sich in versions/k-/kitten.json. Dies sollte ein Objekt der obersten Ebene mit nur einem einzigen Feld sein: "versions". Dieses Feld sollte ein Array von Versionsobjekten enthalten:

• Die betreffende Portversion; sollte genau mit der vcpkg.json Datei identisch sein, einschließlich der Versionsfelder und "port-version".
• The "path" field: a relative directory, root at the base of the registry (in other words, the directory where versions is located), to the port directory. Es sollte etwa wie "$/path/to/port/dirfolgt aussehen:

Das Versionsfeld für Ports mit veralteten CONTROL Dateien ist "version-string".

Im Allgemeinen ist es nicht wichtig, wo Sie Portverzeichnisse platzieren. Das Idiom in vcpkg folgt jedoch etwas genau dem, was die in vcpkg-Registrierung integrierte Registrierung tut: Ihr kitten Port bei der Version x.y.z sollte platziert ports/kitten/x.y.zwerden, wobei portierte Versionen wie sie passen (obwohl da # es sich nicht um ein gutes Zeichen handelt, für Dateinamen zu verwenden, vielleicht verwenden _).

Warnung

Ein sehr wichtiger Bestandteil der Registrierungen ist, dass Versionen niemals geändert werden sollten. Man sollte niemals eine vorhandene Version entfernen oder ändern. Ihre Änderungen an Ihrer Registrierung sollten das Verhalten für nachgeschaltete Benutzer nicht ändern.

Hier ist ein Beispiel für eine gültige Versionsdatenbank für einen kitten Port mit einer Version:

{
  "versions": [
    {
      "version": "2.6.2",
      "port-version": 0,
      "path": "$/ports/kitten/2.6.2_0"
    }
  ]
}

Hinzufügen einer neuen Version

Im Gegensatz zu Git-Registrierungen erfordert das Hinzufügen einer neuen Version zu einer Dateisystemregistrierung meist viel Kopieren. Als Erstes müssen Sie die neueste Version Ihres Ports in ein neues Versionsverzeichnis kopieren, die Version und "port-version" die Felder nach Bedarf aktualisieren und dann mit overlay-ports:

vcpkg install kitten --overlay-ports=ports/kitten/new-version.

Nachdem Sie ihre Tests abgeschlossen haben, können Sie diese neue Version am Anfang Ihrer versions/k-/kitten.json:

{
  "versions": [
    {
      "version": "2.6.3",
      "port-version": 0,
      "path": "$/ports/kitten/2.6.3_0"
    },
    {
      "version": "2.6.2",
      "port-version": 0,
      "path": "$/ports/kitten/2.6.2_0"
    }
  ]
}

Anschließend möchten Sie auch Ihre versions/baseline.json neue Version ändern (denken Sie daran, vorhandene Basispläne nicht zu ändern):

{
  "2021-04-17": {
    "kitten": {
      "baseline": "2.6.3",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  },
  "2021-04-16": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  },
  "2021-04-15": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 1
    }
  }
}

Und Sie haben es geschafft!