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

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

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

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

この記事では、次の内容について説明します。

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

前提条件

• GitHub アカウント
• 独自の vcpkg Git レジストリ
• バイナリ キャッシュとアセット キャッシュのチュートリアルの完了。
• GitHub Actions ワークフローに関する知識

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

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

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

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

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

steps:
  - 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: 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"

この例では、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 アクションワークフローの手順にそのまま含める必要があります。 この手順では、バックエンドが 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 レジストリのテストには適していません。 代わりに、この記事で説明されている手順に従うことをお勧めします。

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

コマンドを 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 に指示します。 上記の 2 つの手順で、独自のレジストリが作成されていないことに 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 レジストリに対する認証
• GHA キャッシュを使用してバイナリ キャッシュを設定する
• 資産キャッシュを設定する
• バイナリ キャッシュリファレンス
• 資産キャッシュリファレンス
• オーバーレイ ポート
• マニフェスト モード
• vcpkg.json
• vcpkg-configuration.json
• vcpkg 構成環境変数