Vytváření registrů
Informace o využívání registrů najdete v tématu Použití registrů.
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
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"
.
Upozornění
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
.
Upozornění
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 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ř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.json
zaří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č!
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í".
Upozornění
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.json
registru, 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ář, kdeversions
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 _
).
Upozornění
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"
}
]
}
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á!
Zpětná vazba k produktu vcpkg
vcpkg je open source projekt. Vyberte odkaz pro poskytnutí zpětné vazby: