GitHub Actions で vcpkg を使用してカスタム レジストリ ポートをテストする

vcpkg ポートのカスタム レジストリを設定したら、Continuos Integration (CI) を追加して、すべての依存関係が正常にビルドできることを検証できます。

Microsoft/vcpkg のメイン vcpkg レジストリは、Azure DevOps Pipelines を使用して vcpkg チームによってテストされます。 これにより、新しいパッケージを追加したり、既存のパッケージを更新したりしても、コンシューマーが中断されることはありません。

この記事では、独自のレジストリで vcpkg ポートをテストする CI 環境を設定する方法について説明します。

この記事では、GitHub Actions で実行されているレジストリの CI ワークフローを設定する方法について説明します。

• GitHub Actions ワークフローのバイナリ キャッシュとアセット キャッシュを設定する
• レジストリのポートをテストするワークフローを設定する

[前提条件]

• GitHub のアカウント
• vcpkg Git レジストリ
• バイナリ キャッシュのチュートリアルを読む
• 資産キャッシュのチュートリアルを読む

GitHub Actions ワークフローのバイナリ キャッシュとアセット キャッシュを設定する

大量のポートのコレクションをテストすることは、時間とコンピューティング能力の両方でコストのかかる作業です。 ポートに CI を使用する前に、GitHub アクション ワークフロー用のバイナリ キャッシュと資産キャッシュの設定に投資することを強くお勧めします。

バイナリ キャッシュは、変更されていないパッケージがすべての CI 実行で再構築されないようにすることで、CI シナリオに最も大きな利点をもたらします。 資産キャッシュは、実行中にパッケージ用にダウンロードされた成果物をミラー化し、その後の実行時にキャッシュされた成果物を使用します。 また、アップストリーム リポジトリの信頼性が低い問題 (ダウンロード URL の破損など) を軽減するのにも役立ちます。

これらのキャッシュを設定する方法の詳細な手順については、 バイナリ キャッシュ と 資産キャッシュ に関する記事を参照してください。

例: GitHub Actions ワークフローで資産とバイナリ キャッシュを有効にする

env:
  FEED_URL: https://nuget.pkg.github.com/<OWNER>/index.json

steps:
  - name: Install vcpkg ports
    run: "${{ github.workspace }}/vcpkg/vcpkg install"
    env: 
      X_VCPKG_ASSET_SOURCES: "clear;x-azurl,https://my.domain.com/container,{{ secrets.SAS }},readwrite"
      VCPKG_BINARY_SOURCES: "clear;nuget,https://nuget.pkg.github.com/<OWNER>/index.json,readwrite"

この例では、GitHub Actions ワークフローでバイナリ キャッシュとアセット キャッシュを設定する方法を示します。 このスニペットは、独自のワークフローの YAML ファイルで使用するように調整する必要があります。

このスニペットを分解します。

X_VCPKG_ASSET_SOURCES は、vcpkg で資産キャッシュを構成するために使用される環境変数です。 この例では、 x-azurl,https://my.domain.com/container,{{secrets.SAS}},readwriteに設定されています。 x-azurl バックエンドは、ストレージ プロバイダーとして Azure Storage コンテナーを使用するように vcpkg に指示します。 x-azurlの後に、コンマ (,) で区切られた 3 つのパラメーターが続きます。

• https://my.domain.com/container はストレージ コンテナーの URL です。
• {{secrets.SAS}} は、ストレージ コンテナーに対して認証する SAS トークンを含む GitHub Actions シークレット変数です。
• readwrite は、資産キャッシュの読み取りと書き込みのアクセス許可を設定します。 つまり、この資産キャッシュは、成果物を格納するために使用されるだけでなく、成果物から成果物を復元するために使用されます。

VCPKG_BINARY_SOURCES は、vcpkg でバイナリ キャッシュを構成するために使用される環境変数です。 この例では、 clear;x-gha,readwriteに設定されています。 これにより、バイナリ キャッシュの GitHub Actions Cache バックエンドが有効になります。 このバックエンドを正常に有効にするには、ワークフローに追加の手順が必要です。

次の手順は、GitHub アクション ワークフローの手順 as-is 含める必要があります。 この手順では、 x-gha バックエンドで必要な 2 つの環境変数をエクスポートして動作させ、vcpkg を含むタスクの前に実行する必要があります。

- name: Enable GitHub Actions Cache backend
  uses: actions/github-script@v7
  with:
  script: |
    core.exportVariable('ACTIONS_CACHE_URL', process.env.ACTIONS_CACHE_URL || '');
    core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');

資産キャッシュとバイナリ キャッシュの機能に関するドキュメントを参照して、これらのすべてが機能する方法の詳細について説明します。

レジストリのポートをテストするワークフローを設定する

CI 環境のバイナリ キャッシュとアセット キャッシュを設定したら、次の手順として、レジストリのすべてのポートをテストするワークフローを設定します。 このワークフローをスケジュールに従って実行するか、新しいコミットまたはプル要求によってトリガーするかを決定できます。

メイン vcpkg レジストリでは、vcpkg プロジェクトのニーズに合わせて調整された vcpkg ci コマンドを使用します。これは、vcpkg のコンシューマーが安定した状態を維持したり使用したりするためのものではありません。 そのため、独自の vcpkg レジストリのテストには適していません。 代わりに、この記事で説明されている手順に従うことをお勧めします。

マニフェスト ファイルを使用してすべてのポートを含める

vcpkg ci コマンドを使用する代わりに、マニフェスト ファイルを使用して、レジストリ内のすべてのパッケージに依存するビルドを作成することをお勧めします。

次の例では、仮想 vcpkg レジストリ内のすべてのポートをテストするマニフェスト ファイルを作成します。 依存関係の一覧を置き換えて、レジストリ内のすべてのポートを含め、リポジトリのルートに配置します。

vcpkg.json

{
  "dependencies": [
    "beicode",
    "beison"
  ]
}

独自のポートは、メインの vcpkg レジストリまたはその他のサード パーティのレジストリに依存している可能性があります。その場合は、 vcpkg-configuration.json ファイルにこれらのレジストリを追加する必要があります。 vcpkg は、追加の構成なしでメイン レジストリからパッケージを解決できますが、バージョン管理の目的でレジストリの一覧に明示的に追加することを強くお勧めします。 これにより、基になるポート バージョンのセットを制御できます。 レジストリのベースラインの管理に役立つ vcpkg x-update-baseline コマンド を確認します。

vcpkg-configuration.json

{
  "default-registry": null,
  "registries": [
    {
      "kind": "git",
      "repository": "https://github.com/Microsoft/vcpkg",
      "baseline": "42bb0d9e8d4cf33485afb9ee2229150f79f61a1f",
      "packages": ["*"]
    }
  ]
}

詳細については、 vcpkg.json と vcpkg-configuration.json のリファレンス記事を参照してください。 マニフェスト モードのドキュメントを読んで、これらがどのように連携するかを理解してください。

GitHub Actions ワークフローで vcpkg を取得する

次に、ワークフローで使用するために vcpkg を取得する必要があります。 vcpkg をインストールするには、次の手順を追加します。

steps:
- uses: actions/checkout@v4
  with:
    repository: "https://github.com/Microsoft/vcpkg"
    path: "vcpkg"

- name: Bootstrap vcpkg
  run: "${{ github.workspace }}/vcpkg/bootstrap-vcpkg.sh"
  shell: bash

これらの手順が完了したら、vcpkg 実行可能ファイルを使用する必要があります。

vcpkg インストールを実行してポートをビルドする

最後の手順では、すべてのポートをビルドするように vcpkg に指示します。 上記のいくつかの手順を作成した vcpkg-configuration.json に、独自のレジストリが存在していないことに気付いたかもしれません。 その理由は、リポジトリで公開されているバージョンではなく、現在作業ディレクトリにあるポートのバージョンをテストするためです。

そのためには、環境変数をレジストリのVCPKG_OVERLAY_PORTS ディレクトリに設定して、レジストリのportsとして追加する必要があります。

次のスニペットは、レジストリのポートをオーバーレイ ポートとして設定し、マニフェスト モードで vcpkg install 実行して、すべてのカスタム ポートをインストールする方法を示しています。

  - name: some vcpkg task
    run: "${{ github.workspace }}/vcpkg/vcpkg install"
    env: 
      X_VCPKG_ASSET_SOURCES: "clear;x-azurl,https://my.domain.com/container,{{ secrets.SAS }},readwrite"
      VCPKG_BINARY_SOURCES: "clear;x-gha,readwrite"
      VCPKG_OVERLAY_PORTS: "${{ github.workspace }}/ports"

この例では、 vcpkg.json ファイルがレジストリのリポジトリのルートに作成されていることを前提としています。

ワークフローの YAML ファイルをすべてまとめると、次のようになります。

.github/workflows/test-ports.yml

name: Test vcpkg ports

on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["main"]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4
    
    - name: Acquire vcpkg
      uses: actions/checkout@v4
      with:
        repository: "Microsoft/vcpkg"
        path: vcpkg

    - name: Bootstrap vcpkg
      run: "${{ github.workspace }}/vcpkg/bootstrap-vcpkg.sh"
      shell: bash

    - name: Enable GitHub Actions Cache backend
      uses: actions/github-script@v7
      with:
        script: |
          core.exportVariable('ACTIONS_CACHE_URL', process.env.ACTIONS_CACHE_URL || '');
          core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');

    - name: Build ports
      run: ${{ github.workspace }}/vcpkg/vcpkg install
      env:
        X_VCPKG_ASSET_SOURCES: "clear;x-azurl,https://your.domain.com/container,${{ secrets.SAS }},readwrite"
        VCPKG_BINARY_SOURCES: "clear;x-gha,readwrite"
        VCPKG_OVERLAY_PORTS: "${{ github.workspace }}/ports"
      shell: bash

これは、レジストリのポートをテストするための CI ワークフローの基本的な構造です。 プライベート リポジトリまたは NuGet フィードに対する認証には、追加の作業が必要になる場合があります。

また、 vcpkg.json ファイルの生成を自動化する手順や、レジストリに新しく追加されたポートがテストから除外されていないことを確認する手順を追加することもできます。

次のステップ

次の記事は、CI 環境を設定するときに役立つ場合があります。

• プライベート Git レジストリに対する認証
• 資産キャッシュを設定する
• バイナリ キャッシュリファレンス
• 資産キャッシュリファレンス
• オーバーレイ ポート
• マニフェスト モードの を する
• vcpkg.json
• vcpkg-configuration.json
• vcpkg 構成環境変数