レジストリの概念

概要

vcpkg は、https://github.com/Microsoft/vcpkg で ポートにパッケージ化されたライブラリの選択をホストします。 このポートのコレクションは、キュレーションレジストリと呼ばれます。 ただし、vcpkg はキュレーションされたレジストリに限定されません。 ユーザーは、カスタム レジストリを作成することで、ポートの選択を拡張できます。

レジストリは、特定の構造に配置されたポートとヘルパー ファイルのコレクションです。 レジストリ構造に従うことで、キュレーションされたレジストリ内のポートに提供されるのと同じ機能 (バージョン管理、バイナリ キャッシュ) を使用して、レジストリに含まれるポートをインストールできます。

現在、レジストリには次の 3 種類があります。

• 組み込みレジストリ、
• Git レジストリ、および
• ファイルシステムレジストリ

vcpkg は、vcpkg-configuration.json ファイルを使用して、カスタム レジストリで使用可能なポートを検討するように指示できます。 プロジェクトでカスタム レジストリを使用する方法のチュートリアルについては、「チュートリアル: Git ベースのレジストリ からの依存関係のインストール」を参照してください。

レジストリ構造

vcpkg がレジストリとインターフェイスするには、次の構造に準拠している必要があります。

• ports という名前のディレクトリにはポートのコレクションが含まれています。各サブディレクトリには、サブディレクトリ名と一致する特定のポートが含まれています。 たとえば、ポート foo のファイルは ports/fooにあります。
• versions という名前のディレクトリには、バージョンのデータベースを構成するファイルが含まれています。

例: レジストリ構造

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

バージョン データベース

すべてのレジストリには、バージョンのデータベースを含むレジストリのルートにある versions ディレクトリが含まれています。

バージョン データベースには、次の 2 つのコンポーネントがあります。

• ベースライン ファイル
• そのバージョンのファイル

ベースライン ファイルは、versions ディレクトリのルートにある baseline.json という名前の JSON ファイルです。

バージョン ファイルは、使用可能なポートと同じ名前の JSON ファイルです。 versions/<prefix>/<port name>.jsonに存在する必要があります。ここで、<prefix> はポート名の最初の文字の後にハイフンが続きます。 たとえば、ポート foo のバージョン ファイルは、versions/f-/foo.jsonにある必要があります。

二つの目的があるのが、バージョンファイルです。

• 各ポートの使用可能なすべてのバージョンを一覧表示する
• 各バージョンの取得場所を示します。

バージョン ファイルの形式は、レジストリの種類によって異なります。

ベースライン ファイル

すべてのレジストリには、その種類に関係なく、versions/baseline.jsonにある baseline.json という名前のファイルが含まれている必要があります。

ベースライン ファイルの目的は、レジストリ内のすべてのポートで最新と見なされるバージョンのセットを記述することです。 このファイルは、新しいバージョンのポートがレジストリに追加されるたびに更新されることが予想されます。

このファイルは、プロパティがベースライン オブジェクトという名前の 1 つのオブジェクトで構成される JSON ファイルです。 各ベースライン オブジェクトのプロパティはポート名であり、値はバージョン エントリです。 レジストリリファレンス 記事では、ベースライン ファイルのレイアウトについて詳しく説明します。

各ベースライン バージョン エントリは、次のプロパティを持つオブジェクトです。

• baseline: 値は、対応する vcpkg.json ファイルと一致するポートのバージョンです。
• port-version: 値は、対応する vcpkg.json ファイルと一致するポートの port-version です。

ベースライン ファイルの例

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

次のリファレンス ドキュメントを参照してください。

• Git レジストリ のベースライン ファイル レイアウト
• ファイルシステム レジストリの のベースライン ファイル レイアウト

各種バージョンのファイル

レジストリ内の各ポートには、対応するバージョン のファイルがあります。 バージョン ファイルは versions/<prefix>/<port name>.json に格納されます。ここで、<prefix> はポート名の最初の文字の後にハイフンが続きます。 たとえば、ポート foo のバージョン ファイルは versions/f-/foo.jsonにあります。

バージョンファイルの目的は二つあります。

• 各ポートの使用可能なすべてのバージョンを一覧表示する
• これらの各バージョンの取得場所をポイントする

バージョン ファイルのレイアウトは、"versions" 配列を含むオブジェクトであり、その配列内の各エントリはバージョン オブジェクトです。 バージョン オブジェクトには、次のプロパティが含まれている必要があります。

• バージョン プロパティ: プロパティのキーと値は、vcpkg.json ファイル内のポートで使用されるキーと値と一致する必要があります。 キーは、version、version-semver、version-date、または version-stringのいずれかである必要があります。値は、ポートのマニフェスト ファイル (vcpkg.json) に表示されるバージョンである必要があります。
• port-version: 値はポートの vcpkg.json ファイルに表示されるポートの port-version です。
• git-tree: (Git レジストリでのみ) 値は、ポートのディレクトリに対応する git ツリー SHA です。 これは、ポートのディレクトリの内容をハッシュすることによって計算される SHA です。この git ツリー SHA を Git で使用して、指定された git ツリーに一致するポートの内容を取得できます。 これにより、vcpkg はレジストリの Git 履歴から古いバージョンのポートを取得できます。 特定のポート バージョンに対してこの値を取得する方法については、git レジストリ セクションを参照してください。
• path: (ファイルシステム レジストリでのみ) 値は、特定のバージョンのポート ファイルを含むディレクトリへの完全なパスです。

ファイルシステム レジストリ バージョン ファイルの例

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

次のリファレンス ドキュメントを参照してください。

• Git レジストリの各種バージョンのファイル レイアウト
• ファイルシステム レジストリのバージョン情報ファイルのレイアウト

組み込みレジストリ

組み込みレジストリは、特殊な種類のレジストリです。 これは、クラシック モードの で使用される既定レジストリです。 マニフェスト モード では、既定のレジストリ 指定されていない場合、vcpkg は組み込みレジストリを暗黙的に使用します。

組み込みレジストリとは、vcpkg リポジトリを https://github.com/Microsoft/vcpkgから git clone したときに作成されたキュレーションされたレジストリのローカル コピーを指します。 一部の操作では、VCPKG_ROOT 環境変数 が組み込みのレジストリを指していることを想定しています。

vcpkg が "one liner" または Visual Studio インストーラーを使用して取得された場合、組み込みレジストリは、https://github.com/Microsoft/vcpkg リポジトリを指 Git レジストリと同じになります。

Git レジストリ

Git レジストリは、レジストリ構造に従い、Git の機能を利用してレジストリ内のポートのバージョン管理を提供するリポジトリです。 https://github.com/Microsoft/vcpkg でキュレーションされたレジストリは、Git レジストリの実装です。

Git レジストリは任意の Git リポジトリ プロバイダーでホストできるため、選択した Git ホスティング サービスを使用してカスタム レジストリへのアクセスを制御しながら、レジストリを簡単に共有できます。

Git レジストリは、カスタム レジストリを実装するための推奨される方法です。 バージョン管理メカニズムはキュレーションされたレジストリで使用されるのと同じであるため、Git レジストリでは、x-add-version を使用してバージョン データベース ファイルを管理できます。

Git レジストリの実装の詳細については、レジストリのリファレンス を参照してください。

Git レジストリへの新しいバージョンの追加

x-add-version コマンドを使用して、新しいポートまたは新しいバージョンをレジストリに追加できます。 このコマンドを使用してバージョンを追加する場合は、次の点に注意してください。

重要

新しいバージョンを追加するときは、バージョン履歴の書き換えを回避するために、ポートの宣言されたバージョンを必ず、まだ公開されていないバージョンに更新してください。

ポートを変更するときは、最初の手順として、vcpkg.json ファイル内のバージョンを増やす必要があります。 変更にパッケージの アップストリーム バージョンの更新が含まれている場合は、必ず port-version を 0に設定してください。それ以外の場合は、port-version を 1 つずつ増やすことを忘れないでください。

x-add-version コマンド では、バージョン データベースを更新する前に、すべてのポート変更がリポジトリにコミットされている必要があります。

例: 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

リダイレクト オプション --x-builtin-ports-root と --x-builtin-registry-versions-dir は、レジストリの ports ディレクトリと versions ディレクトリをそれぞれ指している必要があります。

x-add-version コマンドが正常に実行されたら、バージョン ファイルの変更を含むように最後のコミットを修正します。

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

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

ファイルシステム レジストリは、ファイルシステム上に存在するレジストリの実装です。 これらは一般的なレジストリ構造に従いますが、Git を使用してバージョン管理機能を提供することはありません。 代わりに、ポートの各バージョンに対して個別のパスを使用して、バージョン コントロールのプリミティブ形式を使用します。

この種のレジストリは、ポートのテストグラウンドにしたり、Git 以外のバージョン管理システムのレジストリの代替手段を提供したりするのに適しています。 ファイル システム レジストリは、ポートの大規模なコレクションには推奨されません。また、この種のレジストリのバージョン データベース ファイルを操作するためのツールは提供されていません。

ファイルシステム レジストリを実装する方法の詳細については、レジストリのリファレンス を参照してください。

レジストリを消費する

プロジェクトでカスタム レジストリを使用するには、プロジェクトの マニフェスト ファイル (vcpkg.json)の横に 構成ファイル (vcpkg-configuration.json) を作成する必要があります。

既定のレジストリ

ポート名を解決する際、既定のレジストリは、ポート名が registries 配列内の他のレジストリによって宣言されたパッケージ パターンのいずれにも一致しない場合、フォールバックとして機能します。

カスタム レジストリを使用していないユーザーにとって便利な方法として、vcpkg は既定のレジストリとして 組み込みレジストリを暗黙的に追加します。 この動作を変更するには、既定のレジストリを任意のレジストリに設定するか、完全に無効化することができます。 default-registry プロパティ。

例: カスタム レジストリを既定として設定する

vcpkg-configuration.json

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

例: 既定のレジストリを無効にする

vcpkg-configuration.json

{
  "default-registry": null
}

レジストリ配列

vcpkg でインストールできるポートの選択を拡張するには、registries 配列を使用して追加のレジストリを指定できます。

例: カスタム レジストリを構成に追加する

手記

レジストリの種類によっては、registries 配列に異なる情報を指定する必要がある場合があります。 各レジストリの種類に必要なプロパティについては、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" ]
    }
  ]
}

レジストリの推奨プラクティス

バージョン履歴を書き換えない

バージョンがバージョン ファイルに発行されたら、git レジストリまたはファイル システム レジストリ内のディレクトリ内の関連付けられている git-tree を変更しないでください。

vcpkg の設計原則の 1 つは、インストールされている依存関係のバージョンがユーザーの介入なしに変更されないことです。 git-tree エントリを変更してバージョンファイル履歴を書き換える場合、この原則に違反します。

既存のバージョンに問題がある場合は、新しい port-versionを作成することをお選びください。

バージョン ファイルを削除しない

手記

このセクションは、Git レジストリ にのみ適用されます

レジストリからポートを削除する場合は、ポート ディレクトリとそのエントリからその内容をベースライン ファイルから削除します。 ただし、関連付けられているバージョンのファイルを削除しないでください。

ポートがレジストリに存在しなくなった場合でも、バージョン ファイルが残っている限り、ポートのユーザーは、バージョンの overridesを使用して古いバージョンをインストールできます。

次のステップ

次に試すタスクを次に示します。

• 独自の Git ベースのレジストリを作成する
• カスタム レジストリからパッケージをインストールする
• レジストリのリファレンス ドキュメントを読む