Delen via

Concepten voor registers

  • Artikel

Overzicht

vcpkg host een selectie van bibliotheken die zijn verpakt in poorten op https://github.com/Microsoft/vcpkg. Deze verzameling poorten wordt het gecureerde registergenoemd. Vcpkg is echter niet beperkt tot het gecureerde register. Gebruikers kunnen de selectie van poorten uitbreiden door aangepaste registers te maken.

Een register is een verzameling poorten en helperbestanden die in een specifieke structuur zijn gerangschikt. Door de registerstructuur te volgen, kunnen poorten in een register worden geïnstalleerd met dezelfde functies (versiebeheer, binaire caching) aangeboden aan poorten in het gecureerde register.

Er zijn momenteel drie soorten registers:

vcpkg kan worden geïnstrueerd om te overwegen welke poorten beschikbaar zijn in aangepaste registers met behulp van een vcpkg-configuration.json bestand. Zie het artikel Zelfstudie: Een afhankelijkheid van een Git-register installeren voor een handleiding over het gebruik van aangepaste registers in uw projecten.

Registerstructuur

Om vcpkg te laten interfacen met een register, moet deze voldoen aan de volgende structuur:

  • Een map met de naam ports bevat de verzameling poorten, waarbij elke submap een specifieke poort bevat die overeenkomt met de naam van de submap. De bestanden voor poort foo bevinden zich bijvoorbeeld in ports/foo.
  • Een map met de naam versions bevat de bestanden die bestaan uit de versiesdatabase.

Voorbeeld: registerstructuur

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

Versiesdatabase

Alle registers bevatten een versions map in de basisdirectory van het register die de database versiesbevat.

Er zijn twee onderdelen voor de versiesdatabase:

  • Het basislijnbestand
  • De versiebestanden

Het basislijnbestand is een JSON-bestand met de naam baseline.json dat zich in de hoofdmap van de map versions bevindt.

De versiesbestanden zijn JSON-bestanden met dezelfde namen als de beschikbare poorten. Ze moeten bestaan op versions/<prefix>/<port name>.json, waarbij <prefix> de eerste letter van de poortnaam is, gevolgd door een afbreekstreepje. Bijvoorbeeld, het versiebestand voor poort foo moet zich op versions/f-/foo.jsonbevinden.

Het doel van het versiebestand is tweeledig.

  • Alle beschikbare versies van elke poort weergeven
  • Wijs de ophaallocaties van elke versie aan.

De indeling van het versiebestand is afhankelijk van het type register.

Basislijnbestand

Alle registers, ongeacht hun soort, moeten een bestand met de naam baseline.json in versions/baseline.jsonbevatten.

Het doel van het basislijnbestand is om de set versies te beschrijven die als de meest recente worden beschouwd voor alle poorten in het register. Er wordt verwacht dat dit bestand wordt bijgewerkt telkens wanneer een nieuwe versie van een poort wordt toegevoegd aan het register.

Het bestand is een JSON-bestand dat bestaat uit één object waarvan de eigenschappen de naam basislijnobjecten hebben. De eigenschappen van elk basislijnobject zijn poortnamen, waarvan de waarden versievermeldingen zijn. In het naslaginformatie over registers artikel wordt de indeling van basislijnbestanden uitgebreider beschreven.

Elke vermelding van de basislijnversie is een object met de volgende eigenschappen:

  • baseline: de waarde is de versie van de poort die overeenkomt met het bijbehorende vcpkg.json-bestand.
  • port-version: de waarde is de port-version van de poort die overeenkomt met het bijbehorende vcpkg.json-bestand.

Voorbeeld van basislijnbestand

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

Raadpleeg de referentiedocumentatie voor:

Versiesbestanden

Elke poort in het register heeft een bijbehorend versiebestand. Versiesbestanden worden opgeslagen op versions/<prefix>/<port name>.json, waarbij <prefix> de eerste letter van de poortnaam is, gevolgd door een afbreekstreepje. Het versiebestand voor poort foo bevindt zich bijvoorbeeld op versions/f-/foo.json.

Het doel van het versiebestand is tweeledig.

  • Alle beschikbare versies van elke poort weergeven
  • Wijs de ophaallocaties van elk van deze versies aan

De indeling van het versiebestand is een object met een "versions" matrix, waarbij elke vermelding in die matrix een versieobject is. Een versieobject moet de volgende eigenschappen bevatten:

  • Een versie-eigenschap: de sleutel en waarde van de eigenschap moeten overeenkomen met de sleutel en waarde die worden gebruikt door de poort in het vcpkg.json bestand. De sleutel moet een van version, version-semver, version-dateof version-stringzijn ; de waarde moet de versie zijn zoals deze wordt weergegeven in het manifestbestand van de poort (vcpkg.json).
  • port-version: de waarde is de port-version van de poort, zoals deze wordt weergegeven in het vcpkg.json-bestand van de poort.
  • git-tree: (alleen in Git-registraties) is de waarde de git-tree SHA die overeenkomt met de map van de poort. Dit is een SHA die wordt berekend door de inhoud van de map van de poort te hashen; deze git-tree SHA kan door Git worden gebruikt om de inhoud van de poort op te halen die overeenkomt met de opgegeven git-tree. Hierdoor kan vcpkg oude versies van poorten ophalen uit de Git-geschiedenis van registers. Lees de sectie git-registers voor meer informatie over het verkrijgen van deze waarde voor een bepaalde poortversie.
  • path: (alleen in bestandssysteemregisters) is de waarde het volledige pad naar een map met de poortbestanden voor de specifieke versie.

Voorbeeld van een bestandssysteemregisterversiebestand

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

Raadpleeg de referentiedocumentatie voor:

Ingebouwd register

Het ingebouwde register is een speciaal type register. Het is het standaardregister dat wordt gebruikt in klassieke modus. In manifestmodus, wanneer een standaardregister niet is opgegeven, maakt vcpkg impliciet gebruik van het ingebouwde register.

Het ingebouwde register verwijst naar de lokale kopie van het gecureerde register dat is gemaakt wanneer u de vcpkg-opslagplaats van https://github.com/Microsoft/vcpkggit clone. Sommige bewerkingen verwachten dat de VCPKG_ROOT omgevingsvariabele verwijst naar een ingebouwd register.

Als vcpkg wordt verkregen via de "one-liner" of het Visual Studio-installatieprogramma, wordt het ingebouwde register gelijk aan een Git-register, dat naar de https://github.com/Microsoft/vcpkg opslagplaats verwijst.

Git-registries

Een Git-register is een opslagplaats die de registerstructuur volgt en gebruikmaakt van de mogelijkheden van Git om versiebeheer voor de poorten in het register te bieden. Het gecureerde register op https://github.com/Microsoft/vcpkg is een implementatie van een Git-register.

Git-registers kunnen worden gehost in elke Git-opslagplaatsprovider, zodat u de door u gekozen Git-hostingservice kunt gebruiken om de toegang tot uw aangepaste register te beheren en uw register ook eenvoudig te delen.

Git-registers zijn de aanbevolen methode voor het implementeren van een aangepast register. Omdat het versiebeheermechanisme hetzelfde is dat wordt gebruikt door het gecureerde register, kunnen Git-registers gebruikmaken van de x-add-version om uw versiedatabasebestanden te beheren.

Zie de registerreferentie voor implementatiedetails van Git-registries.

Een nieuwe versie toevoegen aan een Git-register

De opdracht x-add-version kan worden gebruikt om een nieuwe poort of een nieuwe versie aan het register toe te voegen. Wanneer u versies toevoegt met deze opdracht, moet u rekening houden met een aantal dingen:

Belangrijk

Wanneer u een nieuwe versie toevoegt, moet u altijd de gedeclareerde versie van de poort bijwerken naar een versie die nog niet is gepubliceerd, om te voorkomen dat de versiegeschiedenis opnieuw wordt geschreven.

Wanneer u wijzigingen aanbrengt in een poort, moet de eerste stap zijn om de versie in het vcpkg.json-bestand te verhogen. Als uw wijzigingen een update bevatten van de upstream- versie van het pakket, moet u de port-version instellen op 0; vergeet niet om de port-version met één te verhogen.

De x-add-version opdracht vereist dat al uw poortwijzigingen worden doorgevoerd in de opslagplaats voordat u de versiedatabase bijwerkt.

Voorbeeld: een nieuwe poortversie toevoegen aan een Git-register

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

De omleidingsopties --x-builtin-ports-root en --x-builtin-registry-versions-dir moeten respectievelijk verwijzen naar de ports en versions mappen van uw register.

Zodra de opdracht x-add-version succesvol wordt uitgevoerd, wijzigt u de laatste commit om de versiebestandswijzigingen op te nemen.

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

Bestandssysteemregisters

Bestandssysteemregisters zijn een implementatie van een register dat zich op een bestandssysteem bevindt. Ze volgen de algemene registerstructuur, maar maken geen gebruik van Git om versiebeheermogelijkheden te bieden. In plaats daarvan gebruiken ze een primitieve vorm van versiebeheer met behulp van een uniek pad voor elke versie van de poorten.

Dit type register is geschikt als testbasis voor uw poorten of om een alternatief te bieden voor een register in een niet-Git-versiebeheersysteem. Bestandssysteemregisters worden niet aanbevolen voor een grote verzameling poorten en er is geen hulpprogramma's beschikbaar om de versiedatabasebestanden voor dit type register te bewerken.

Zie de naslaginformatie over registers voor meer informatie over het implementeren van een bestandssysteemregister.

Registers gebruiken

Als u een aangepast register in uw project wilt gebruiken, moet u een configuratiebestand (vcpkg-configuration.json) maken naast het manifestbestand (vcpkg.json)van uw project.

Standaardregister

Wanneer poortnamenoplossen, fungeert het standaardregister als terugvaloptie wanneer de naam van een poort niet overeenkomt met een van de pakketpatronen die door andere registers in de registries arrayzijn gedeclareerd.

Als gemak voor gebruikers die niet betrokken zijn bij aangepaste registers, voegt vcpkg impliciet het ingebouwde register toe als het standaardregister. Als u dit gedrag wilt wijzigen, kan het standaardregister worden ingesteld op elk register of volledig worden uitgeschakeld met behulp van de default-registry eigenschap.

Voorbeeld: Een aangepast register als standaard instellen

vcpkg-configuration.json

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

Voorbeeld: Het standaardregister uitschakelen

vcpkg-configuration.json

{
  "default-registry": null
}

Registersmatrix

Als u de beschikbare poorten wilt uitbreiden om te installeren met vcpkg, kunt u extra registers opgeven met behulp van de registries matrix.

Voorbeeld: Aangepaste registers toevoegen aan de configuratie

Notitie

Afhankelijk van het registertype moet u mogelijk andere informatie opgeven in de registries matrix. Zie de vcpkg-configurtion.json referentie voor meer informatie over welke eigenschappen vereist zijn voor elk type register.

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

Versiegeschiedenis niet herschrijven

Zodra een versie naar de versiebestanden is gepubliceerd, mag men de bijbehorende git-tree niet wijzigen in een Git-register of map in een bestandssysteemregister.

Een van de ontwerpprincipes van vcpkg is dat de versies van geïnstalleerde afhankelijkheden niet veranderen zonder tussenkomst van de gebruiker. Het herschrijven van de bestandsgeschiedenis van de versies door een git-tree vermelding te wijzigen, schendt dit principe.

Als de bestaande versie problemen heeft, maakt u liever een nieuwe port-version.

Versiesbestanden niet verwijderen

Notitie

Deze sectie is alleen van toepassing op Git-registers

Wanneer u een poort uit het register verwijdert, verwijdert u de inhoud van de poortmap en de vermelding in het basislijnbestand. Maar het bijbehorende versiebestand niet verwijderen.

Zelfs als er geen poort meer in het register bestaat, kunnen gebruikers van de poort oude versies installeren met behulp van versie overrides.

Volgende stappen

Hier volgen enkele taken om het volgende te proberen: