レジストリの作成

[アーティクル]
06/20/2024

レジストリの使用については、「レジストリの使用」を参照してください。

概要

レジストリは、ポートとそのバージョンのコレクションです。独自のレジストリを作成する場合、レジストリの実装には、git レジストリとファイルシステムレジストリの 2 つの主要な選択肢があります。

Git レジストリは単純な Git リポジトリであり、Git リポジトリの通常のメカニズムを使用してパブリックまたはプライベートに共有できます。たとえば、 vcpkg リポジトリは git レジストリです。

ファイルシステムレジストリは、より多くのテスト環境として設計されています。ファイルシステム上に文字どおり存在することを考えると、共有する唯一の方法は共有ディレクトリを介することです。ただし、ファイルシステムレジストリは、git 以外のバージョン管理システムに保持されているレジストリを表す方法として役立ちます。これは、レジストリをディスクに取り込む何らかの方法があることを前提としています。

レジストリの種類のセットは、時間の経過と同時に拡大することが予想されます。お気に入りのパブリックバージョン管理システムに組み込まれているレジストリのサポートが必要な場合は、PR を開くことをお勧めします。

レジストリの基本的な構造は次のとおりです。

履歴の特定の時点で "最新" と見なされるバージョンのセット ("ベースライン" と呼ばれます)。
すべてのポートのすべてのバージョンのセットと、レジストリでこれらの各ポートを検索する場所。

Git レジストリ

このドキュメントと共にフォローしているため、参照する作業例があると役に立つ場合があります。 1 つを記述し、ここに配置しました。

Northwind Traders: vcpkg レジストリ。

すべての git レジストリには、 versions/baseline.json ファイルが必要です。このファイルには、特定のコミットでの "最新バージョン" のセットが含まれています。 "default" フィールドのみを含む最上位オブジェクトとしてレイアウトされます。このフィールドには、現在最新のバージョンへのオブジェクトマッピングポート名が含まれている必要があります。

有効なbaseline.jsonの例を次に示します。

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

versions ディレクトリには、レジストリに含まれるパッケージのバージョンに関するすべての情報と、それらのバージョンが格納されている場所が含まれます。残りのレジストリは、vcpkg に関する限り、バッキングストアとして機能するだけです。vcpkg によってレジストリがどのように表示されるかを指示するために、 versions ディレクトリ内のもののみが使用されます。

レジストリ内の各ポートは、 <first letter of port>-/<name of port>.jsonとしてバージョンディレクトリに存在する必要があります。つまり、 kitten ポートに関する情報は versions/k-/kitten.jsonに配置されます。これは、 "versions"という 1 つのフィールドのみを持つ最上位オブジェクトである必要があります。このフィールドには、バージョンオブジェクトの配列が含まれている必要があります。

問題のポートのバージョン。は、バージョンフィールドや"port-version"など、vcpkg.json ファイルとまったく同じである必要があります。
"git-tree"フィールドは git ツリーです。つまり、git rev-parse COMMIT-ID:path/to/portを記述すると何が得られます。

非推奨の CONTROL ファイルを含むポートのバージョンフィールドは "version-string"。

警告

レジストリの非常に重要な部分の 1 つは、バージョンを変更必要があるということです。後の ref に更新すると、既存のバージョンが削除されたり変更されたりすることはありません。レジストリを更新しても常に安全である必要があります。

1 つのバージョンを持つ kitten ポートの有効なバージョンデータベースの例を次に示します。

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

一般に、ポートディレクトリを配置する場所は重要ではありません。ただし、vcpkg のイディオムは、組み込みの vcpkg レジストリの動作に従うものです。 kitten ポートは ports/kittenに配置する必要があります。

警告

もう 1 つ注意すべき点は、レジストリを更新するときに、以前のすべてのバージョンにもアクセスできることです。ユーザーはベースラインをコミット IDに設定するため、そのコミット IDは常に存在し、実際にフェッチされる HEAD コミットからアクセスできる必要があります。つまり、HEAD コミットは、以前のすべての HEAD コミットの子である必要があります。

組み込みレジストリ

組み込みレジストリは、特殊な Git レジストリとして扱われます。組み込みレジストリは、リモート URL からフェッチする代わりに、vcpkg クローンの $VCPKG_ROOT/.git ディレクトリを参照します。現在チェックアウトされている $VCPKG_ROOT/versions ディレクトリをバージョン管理情報のソースとして使用します。

新しいバージョンの追加

新しいバージョンのポートの作成には、いくつかの git トリッキーが関係しています。まず、いくつかの変更を加え、必要に応じて "port-version" と通常のバージョンフィールドを更新してから、 overlay-portsでテストします。

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

テストが完了したら、ディレクトリが git の purview の下にあることを確認する必要があります。これを行うには、一時的なコミットを作成します。

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

次に、ディレクトリの Git ツリー ID を取得します。

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

その後、このバージョンをバージョンデータベースに追加できます。 versions/k-/kitten.jsonの上部に追加できます (バージョン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"
    }
  ]
}

次に、新しいバージョンで versions/baseline.json も変更します。

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

現在のコミットを修正します。

> git commit --amend

その後、離れて共有!

ファイルシステムレジストリ

このドキュメントと共にフォローしているため、参照する作業例があると役に立つ場合があります。 1 つを記述し、ここに配置しました。

ファイルシステムレジストリの例。

すべてのファイルシステムレジストリには、 versions/baseline.json ファイルが必要です。このファイルには、特定のバージョンのレジストリの "最新バージョン" のセットが含まれています。これは、バージョン名から "ベースラインオブジェクト" へのマップを含む最上位オブジェクトとしてレイアウトされます。このオブジェクトは、そのバージョンのレジストリの "最新" と見なされるバージョンにポート名をマップします。

ファイルシステムレジストリは、バージョン管理スキームを決定する必要があります。 refs の暗黙的なバージョン管理スキームを持つ git レジストリとは異なり、ファイルシステムレジストリはここでバージョン管理システムに依存できません。可能なオプションの 1 つは、毎日のリリースを行い、"バージョン" を日付にすることです。

警告

発行後にベースラインを変更することはできません。バージョンを変更または更新する場合は、 baseline.json ファイルに新しいベースラインを作成する必要があります。

バージョンの日付を決定したレジストリの有効な baseline.jsonの例を次に示します。

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

問題のポートのバージョン。は、バージョンフィールドや"port-version"など、vcpkg.json ファイルとまったく同じである必要があります。
"path" フィールド: レジストリのベース (つまり、versionsが配置されているディレクトリ) をルートとする相対ディレクトリ。それは "$/path/to/port/dirのようなものになるはずです"

非推奨の CONTROL ファイルを含むポートのバージョンフィールドは "version-string"。

一般に、ポートディレクトリを配置する場所は重要ではありません。ただし、vcpkg のイディオムは、組み込みの vcpkg レジストリの動作にやや近い方法です。バージョンx.y.zのkittenポートは、必要に応じてポートバージョンを追加して、ports/kitten/x.y.zに配置する必要があります (ただし、#はファイル名に使用するのに適した文字ではないため、おそらく_を使用します)。

警告

レジストリの非常に重要な部分の 1 つは、バージョンを変更必要があるということです。既存のバージョンを削除したり変更したりしないでください。レジストリに対する変更は、ダウンストリームユーザーに対する動作を変更しないでください。

1 つのバージョンを持つ kitten ポートの有効なバージョンデータベースの例を次に示します。

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

新しいバージョンを追加する

Git レジストリとは異なり、ファイルシステムレジストリに新しいバージョンを追加するには、多くのコピーが必要です。最初に、ポートの最新バージョンを新しいバージョンのディレクトリにコピーし、必要に応じてバージョンと "port-version" フィールドを更新してから、 overlay-portsでテストします。

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

テストが完了したら、この新しいバージョンを 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"
    }
  ]
}

次に、新しいバージョンでも versions/baseline.json を変更する必要があります (既存のベースラインは変更しないでください)。

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

これで完了です。

次の方法で共有

レジストリの作成

概要

Git レジストリ

組み込みレジストリ

新しいバージョンの追加

ファイルシステムレジストリ

新しいバージョンを追加する

フィードバック

その他のリソース

次の方法で共有

レジストリの作成

概要

Git レジストリ

組み込みレジストリ

新しいバージョンの追加

ファイルシステム レジストリ

新しいバージョンを追加する

フィードバック

その他のリソース

ファイルシステムレジストリ