Koncepty registrů

Přehled

vcpkg hostuje výběr knihoven zabalených do portů v https://github.com/Microsoft/vcpkg. Tato kolekce portů se nazývá kurátorovaný registr. Vcpkg ale není omezen na kurátorovaný registr. Uživatelé můžou rozšířit výběr portů vytvořením vlastních registrů.

Registr je kolekce portů a pomocných souborů uspořádaných do konkrétní struktury. Podle struktury registru lze porty obsažené v registru nainstalovat se stejnými funkcemi (správa verzí, binární ukládání do mezipaměti) nabízené portům v kurátorovaném registru.

V současné době existují tři druhy registrů:

• předdefinovaný registr,
• registrů Git a
• registr systému souborů.

Vcpkg lze instruovat, aby zvážil porty dostupné ve vlastních registrech pomocí souboru vcpkg-configuration.json. Podívejte se na článek : Jak nainstalovat závislost z registru založeného na Gitu pro návod, jak používat vlastní registry ve vašich projektech.

Struktura registru

Aby vcpkg mohl interagovat s registrem, musí mít následující strukturu:

• Adresář s názvem ports obsahuje kolekci portů, přičemž každý podadresář obsahuje konkrétní port odpovídající názvu podadresáře. Například soubory pro foo portu se nacházejí v ports/foo.
• Adresář s názvem versions obsahuje soubory, které tvoří verze databáze.

Příklad: struktura registru

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

Databáze verzí

Všechny registry obsahují adresář versions v kořenovém adresáři registru, který obsahuje databázi verzí .

Databáze verzí má dvě komponenty:

• Soubor referenčního plánu
• Soubory verzí

Základní soubor je soubor JSON s názvem baseline.json umístěný v kořenovém adresáři versions.

Soubory verzí jsou soubory JSON se stejnými názvy jako dostupné porty. Musí existovat v versions/<prefix>/<port name>.json, kde <prefix> je první písmeno názvu portu následovaného pomlčkou. Například soubor verzí pro port foo musí být v versions/f-/foo.json.

Účel souboru verzí je dvounásobný:

• Výpis všech dostupných verzí jednotlivých portů
• Ukazujte na umístění získání jednotlivých verzí.

Formát souboru verze závisí na druhu registru.

Směrný soubor

Všechny registry, bez ohledu na jejich druh, musí obsahovat soubor s názvem baseline.json umístěný v versions/baseline.json.

Účelem souboru směrného plánu je popsat sadu verzí, které jsou považovány za nejnovější pro všechny porty v registru. Očekává se, že se tento soubor aktualizuje při každém přidání nové verze portu do registru.

Soubor je soubor JSON složený z jednoho objektu, jehož vlastnosti se nazývají základní objekty. Vlastnosti každého základního objektu jsou názvy portů, jejichž hodnoty jsou položky verze. Referenční článek registrů popisuje rozložení základních souborů podrobněji.

Každá položka základní verze je objekt s následujícími vlastnostmi:

• baseline: Hodnota je verze portu odpovídající příslušnému souboru vcpkg.json.
• port-version: hodnota je port-version portu odpovídající příslušnému souboru vcpkg.json.

Příklad základního souboru

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

Další informace najdete v referenční dokumentaci:

• Základní rozložení souboru pro registry Git
• Základní rozložení souborů pro registr systému souborů

Soubory verzí

Každý port v registru má odpovídající soubor verzí. Soubory verzí se ukládají na versions/<prefix>/<port name>.json , kde <prefix> je první písmeno názvu portu následovaného pomlčkou. Například soubor verzí pro port foo je na versions/f-/foo.json.

Účel souboru verzí je dvounásobný:

• Výpis všech dostupných verzí jednotlivých portů
• Ukazte na umístění uložení každé z těchto verzí.

Rozložení souboru verzí je objekt obsahující pole "versions", přičemž každá položka v této matici je objekt verze. Objekt verze musí obsahovat následující vlastnosti:

• Vlastnost verze: Klíč a hodnota vlastnosti musí odpovídat hodnotám používaným portem v souboru vcpkg.json. Klíč musí být jedním z version, version-semver, version-datenebo version-string; hodnota musí být verze, jak se zobrazí v souboru manifestu portu (vcpkg.json).
• port-version: hodnota je port-version portu tak, jak se zobrazuje v souboru vcpkg.json portu.
• git-tree: (pouze v registrech Gitu) je hodnota SHA stromu git odpovídající adresáři portu. Toto je SHA hodnotou vypočítanou hašováním obsahu adresáře portu; SHA gitového stromu může Git použít k načtení obsahu portu odpovídajícího poskytnutému gitovému stromu. To umožňuje, aby vcpkg načetl staré verze portů z gitové historie registrů. V části registrů Git se dozvíte, jak tuto hodnotu získat pro libovolnou verzi portu.
• path: (pouze v registrech souborového systému) je hodnota úplná cesta k adresáři, který obsahuje portové soubory pro konkrétní verzi.

Příklad souboru registru verze systému souborů

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

Další informace najdete v referenční dokumentaci:

• Rozložení souborů verzí pro registrů Git
• Rozvržení souborů verzí pro registry systému souborů

Integrovaný registr

Integrovaný registr je speciální druh registru. Jedná se o výchozí registr používaný v klasickém režimu. V režimu manifestu, pokud není zadán výchozí registr , nástroj vcpkg implicitně používá integrovaný registr.

Integrovaný registr odkazuje na místní kopii kurátorovaného registru vytvořeného při git clone úložiště vcpkg z https://github.com/Microsoft/vcpkg. Některé operace očekávají, že proměnná prostředí VCPKG_ROOT odkazuje na integrovaný registr.

Pokud se vcpkg získá prostřednictvím "jednoho příkazu" nebo instalátoru Visual Studio, vestavěný registr se stane ekvivalentem Git registru odkazujícího na úložiště https://github.com/Microsoft/vcpkg.

Registry Gitu

Registr Gitu je úložiště, které se řídí strukturou registru a využívá funkce Gitu k poskytování správy verzí portů v registru. Kurátorovaný registr na https://github.com/Microsoft/vcpkg je implementace registru Git.

Registry Gitu je možné hostovat v libovolném poskytovateli úložiště Git, což vám umožní používat zvolenou hostingovou službu Gitu k řízení přístupu k vašemu vlastnímu registru a zároveň usnadňuje sdílení vašeho registru.

Registry Git jsou doporučenou metodou implementace vlastního registru. Vzhledem k tomu, že mechanismus správy verzí je stejný jako kurátorovaný registr, mohou registry Git využívat x-add-version ke správě souborů databáze verzí.

Podrobnosti o implementaci registrů Git najdete v referenčních registrech.

Přidání nové verze do registru Git

Příkaz x-add-version lze použít k přidání nového portu nebo nové verze do registru. Při přidávání verzí pomocí tohoto příkazu je potřeba mít na paměti několik věcí:

Důležitý

Při přidávání nové verze nezapomeňte aktualizovat deklarovanou verzi portu na verzi, která ještě není publikovaná, abyste se vyhnuli přepisu historie verzí.

Při provádění změn portu by prvním krokem mělo být zvýšení jeho verze v souboru vcpkg.json. Pokud vaše změny zahrnují aktualizaci upstreamové verze balíčku, nezapomeňte nastavit port-version na 0; jinak nezapomeňte zvýšit port-version o jeden.

Příkaz x-add-version vyžaduje, aby byly všechny změny portů před aktualizací databáze verzí potvrzeny do úložiště.

Příklad: Přidání nové verze portu do registru Git

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

Možnosti přesměrování --x-builtin-ports-root a --x-builtin-registry-versions-dir by měly odkazovat na adresáře ports a versions registru.

Jakmile se příkaz x-add-version úspěšně spustí, změní poslední potvrzení tak, aby zahrnovalo změny souboru verzí.

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

Registry systému souborů

Registry systému souborů představují implementaci registru, který se nachází v systému souborů. Sledují společnou strukturu registru, ale nepoužívají Git k nabízení funkcí správy verzí. Místo toho používají primitivní formu správy verzí pomocí jedinečné cesty pro každou verzi svých portů.

Tento druh registru je vhodný jako testovací základ pro vaše porty nebo poskytnout alternativu pro registr v systému správy verzí mimo Git. Registry systému souborů se nedoporučují pro velkou kolekci portů a nejsou k dispozici žádné nástroje pro manipulaci se soubory databáze verzí pro tento druh registru.

Podrobnosti o tom, jak implementovat registr systému souborů, najdete v referenčních rejstřících .

Využívání registrů

Pokud chcete v projektu využívat vlastní registr, musíte vytvořit konfigurační soubor (vcpkg-configuration.json) vedle souboru manifestu projektu (vcpkg.json).

Výchozí registr

Při překladu názvů portůfunguje výchozí registr jako záložní, pokud název portu neodpovídá žádnému ze vzorů balíčků deklarovaných jinými registry v poli registries.

Jako pohodlí pro uživatele, kteří nejsou zapojeni do vlastních registrů, vcpkg implicitně přidá předdefinovaný registr jako výchozí registr. Pokud chcete toto chování změnit, můžete výchozí registr nastavit na jakýkoli registr nebo ho úplně zakázat pomocí default-registry je vlastnost.

Příklad: Nastavení vlastního registru jako výchozího

vcpkg-configuration.json

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

Příklad: Zakázání výchozího registru

vcpkg-configuration.json

{
  "default-registry": null
}

Pole registrů

Pokud chcete rozšířit výběr portů dostupných k instalaci pomocí vcpkg, můžete zadat další registry pomocí registries pole.

Příklad: Přidání vlastních registrů do konfigurace

Poznámka

V závislosti na druhu registru může být potřeba zadat různé informace v poli registries. Informace o tom, které vlastnosti jsou požadovány pro jednotlivé typy registru, najdete v referenci vcpkg-configurtion.json.

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

Doporučené postupy pro registry

Nechte historii verzí nezměněnou

Po publikování verze do souborů s verzemi neměňte její svázané git-tree v registru git nebo v adresáři v registru systému souborů.

Jedním z principů návrhu vcpkg je, že verze nainstalovaných závislostí se nemění bez zásahu uživatele. Přepsání historie souborů verzí změnou položky git-tree porušuje tento princip.

Pokud má stávající verze problémy, raději vytvořte nový port-version.

Neodstraňujte soubory verzí

Poznámka

Tato část se týká jenom registrů Gitu.

Při odebírání portu z registru odeberte jeho obsah z adresáře portů a jeho položky v základním souboru. Ale neodstra ňujte jeho přidružený soubor verzí.

I když port v registru již neexistuje, pokud zůstane soubor verzí, mohou uživatelé portu nainstalovat staré verze pomocí verze overrides.

Další kroky

Tady je několik úkolů, které můžete vyzkoušet dál:

• Vytvoření vlastního registru založeného na Gitu
• Instalace balíčků z vlastního registru
• Přečtěte si referenční dokumentaci k registrům.