Vytváření registrů

  • Článek

Informace o využívání registrů najdete v tématu Použití registrů.

Přehled

Registry jsou kolekce portů a jejich verzí. Existují dvě hlavní možnosti implementace pro registry, pokud chcete vytvořit vlastní: registry Git a registry systému souborů.

Registry Gitu jsou jednoduchá úložiště Git a dají se veřejně nebo soukromě sdílet prostřednictvím běžných mechanismů pro úložiště Git. Úložiště vcpkg je například registr Git.

Registry systému souborů jsou navrženy jako více testovacího prostředí. Vzhledem k tomu, že doslova žijí ve vašem systému souborů, jediným způsobem, jak je sdílet, je prostřednictvím sdílených adresářů. Registry systému souborů však mohou být užitečné jako způsob, jak reprezentovat registry uchovávané v systémech správy verzí mimo Git, za předpokladu, že jeden má nějaký způsob, jak získat registr na disk.

Očekáváme, že sada typů registru bude v průběhu času růst; pokud chcete podporovat registry integrované ve vašem oblíbeném systému správy verzí, neváhejte otevřít žádost o přijetí změn.

Základní struktura registru je:

  • Sada verzí, které jsou v určitých časech v historii považovány za nejnovější, označované jako "směrný plán".
  • Sada všechverzíchch

Registry Gitu

Jak sledujete společně s touto dokumentací, může být užitečné mít funkční příklad, na který můžete odkazovat. Napsali jsme ho a dali jsme ho sem:

Microsoft/vcpkg-docs: registr vcpkg.

Všechny registry Gitu musí mít versions/baseline.json soubor. Tento soubor obsahuje sadu "nejnovějších verzí" v určitém potvrzení. Je rozložen jako objekt nejvyšší úrovně obsahující pouze "default" pole. Toto pole by mělo obsahovat názvy portů mapování objektů na verzi, která je aktuálně nejnovější.

Tady je příklad platného baseline.json:

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

Adresář versions obsahuje všechny informace o tom, které verze balíčků jsou obsaženy v registru a kde jsou tyto verze uloženy. Zbytek registru funguje jenom jako záložní úložiště, pokud jde o vcpkg: pouze věci v versions adresáři se použijí k nasměrování toho, jak je registr vidět vcpkg.

Každý port v registru by měl existovat v adresáři verzí jako <first letter of port>-/<name of port>.json; jinými slovy, informace o kitten portu by byly umístěny v versions/k-/kitten.json. To by měl být objekt nejvyšší úrovně pouze s jedním polem: "versions". Toto pole by mělo obsahovat pole objektů verze:

  • Verze dotčeného přístavu; by měl být úplně stejný jako vcpkg.json soubor, včetně polí verze a "port-version".
  • Pole "git-tree" , které je git strom, jinými slovy, co dostanete při psaní git rev-parse COMMIT-ID:path/to/port.

Pole verze pro porty s zastaralými CONTROL soubory je "version-string".

Upozorňující

Jednou z velmi důležitých částí registrů je, že verze by se nikdy neměly měnit. Aktualizace na pozdější odkaz by nikdy neměla odebrat nebo změnit existující verzi. Vždy musí být bezpečné aktualizovat registr.

Tady je příklad platné verze databáze pro kitten port s jednou verzí:

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

Obecně platí, že není důležité umístit adresáře portů. Nicméně, idiom vcpkg je sledovat, co integrované vcpkg registru: váš kitten port by měl být umístěn v ports/kitten.

Upozorňující

Je třeba mít na paměti, že při aktualizaci registru by měly být dostupné i všechny předchozí verze. Vzhledem k tomu, že uživatel nastaví směrný plán na ID potvrzení, musí vždy existovat ID potvrzení a být přístupné z potvrzení HEAD, což je to, co se skutečně načte. To znamená, že potvrzení HEAD by mělo být podřízené všem předchozím potvrzením HEAD.

Předdefinované registry

Předdefinované registry se považují za speciální registry Gitu. Místo načtení ze vzdálené adresy URL se předdefinované registry podívejte do $VCPKG_ROOT/.git adresáře klonu vcpkg. Jako zdroj informací o správě verzí používají aktuálně rezervovaný $VCPKG_ROOT/versions adresář.

Přidání nové verze

Při vytváření nové verze portu je potřeba několik triků gitu. První věcí, kterou je potřeba udělat, je provést nějaké změny, aktualizovat "port-version" a běžné pole verze, jak potřebujete, a pak testovat pomocí overlay-ports:

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

Jakmile dokončíte testování, musíte se ujistit, že je adresář, jak je ve službě Git Purview. Provedete to vytvořením dočasného potvrzení:

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

Pak získejte ID stromu Git v adresáři:

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

Tuto verzi pak můžete přidat do databáze verzí. V horní části svého versions/k-/kitten.jsonzařízení můžete přidat (za předpokladu, že přidáváte verzi 2.6.3#0):

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

Pak budete chtít upravit versions/baseline.json svou novou verzi také:

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

a změnit vaše aktuální potvrzení:

> git commit --amend

a pak se nasdílejte pryč!

Registry systému souborů

Jak sledujete společně s touto dokumentací, může být užitečné mít funkční příklad, na který můžete odkazovat. Napsali jsme ho a dali jsme ho sem:

Příklad registru systému souborů.

Všechny registry systému souborů musí mít versions/baseline.json soubor. Tento soubor obsahuje sadu "nejnovějších verzí" pro určitou verzi registru. Je rozložen jako objekt nejvyšší úrovně obsahující mapu z názvu verze na "základní objekty", které mapují názvy portů na verzi, která se pro danou verzi registru považuje za nejnovější.

Registry systému souborů se musí rozhodnout o schématu správy verzí. Na rozdíl od registrů Gitu, které mají implicitní schéma správy verzí refs, se tady registry systému souborů nemůžou spoléhat na systém správy verzí. Jednou z možných možností je provést denní vydání a mít data "verzí".

Upozorňující

Po publikování nesmí být směrný plán změněn. Pokud chcete změnit nebo aktualizovat verze, musíte v baseline.json souboru vytvořit nový směrný plán.

Tady je příklad platného baseline.jsonregistru, který rozhodl o datech pro jejich verze:

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

Adresář versions obsahuje všechny informace o tom, které verze balíčků jsou obsaženy v registru a kde jsou tyto verze uloženy. Zbytek registru funguje jenom jako záložní úložiště, pokud jde o vcpkg: pouze věci v versions adresáři se použijí k nasměrování toho, jak je registr vidět vcpkg.

Každý port v registru by měl existovat v adresáři verzí jako <first letter of port>-/<name of port>.json; jinými slovy, informace o kitten portu by byly umístěny v versions/k-/kitten.json. To by měl být objekt nejvyšší úrovně pouze s jedním polem: "versions". Toto pole by mělo obsahovat pole objektů verze:

  • Verze dotčeného přístavu; by měl být úplně stejný jako vcpkg.json soubor, včetně polí verze a "port-version".
  • Pole "path" : relativní adresář rootovaný v základu registru (jinými slovy adresář, kde versions se nachází) do adresáře portu. Měl by vypadat nějak takto "$/path/to/port/dir:

Pole verze pro porty s zastaralými CONTROL soubory je "version-string".

Obecně platí, že není důležité umístit adresáře portů. Idiom v vcpkg je však poněkud úzce sledovat, co integrované vcpkg registru: váš kitten port ve verzi x.y.z by se měl umístit do ports/kitten/x.y.z, s verzemi portů připojenými, jak vidíte vhodnou (ačkoli vzhledem k tomu, že # není dobrý znak pro použití pro názvy souborů, možná použít _).

Upozorňující

Jednou z velmi důležitých částí registrů je, že verze by se nikdy neměly měnit. Nikdy byste neměli odebírat nebo měnit existující verzi. Vaše změny v registru by neměly měnit chování podřízených uživatelů.

Tady je příklad platné verze databáze pro kitten port s jednou verzí:

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

Přidání nové verze

Na rozdíl od registrů Git zahrnuje přidání nové verze do registru systému souborů většinou hodně kopírování. První věcí, kterou je potřeba udělat, je zkopírovat nejnovější verzi portu do nového adresáře verzí, aktualizovat verzi a "port-version" pole podle potřeby a pak otestovat pomocí overlay-ports:

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

Jakmile dokončíte testování, můžete tuto novou verzi přidat na začátek svého 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"
    }
  ]
}

Pak budete chtít upravit versions/baseline.json také novou verzi (nezapomeňte upravit stávající směrné plány):

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

A ty jsi hotová!