次の方法で共有

バイナリ キャッシュのトラブルシューティング ガイド

  • [アーティクル]

このガイドは、 binary キャッシュに関する問題が発生しているユーザーを対象としています。

vcpkg デバッグ情報を有効にする

このガイドに従うときは、デバッグ出力を有効にすることを強くお勧めします。

  • クラシック モード: コマンドの呼び出しに --debug を追加します。
  • CMake ツールチェーン: CMake 構成呼び出しまたはCMakePresets.json ファイルに-DVCPKG_INSTALL_OPTIONS="--debug"を追加します。
  • MSBuild/Visual Studio: プロパティ VcpkgAdditionalInstallOptions を --debug に設定します。
  • VCPKG_INSTALL_OPTIONS 環境変数を --debug に設定します。

{url} への NuGet プッシュが失敗する

重要

vcpkg ツールを最新リリースに更新します。 さらに、包括的なエラー ログの デバッグ出力 を有効にします。

NuGet バイナリ ソースを使用すると、次のエラーが表示されます。

Pushing NuGet to {url} failed. Use --debug for more information.

NuGet 構成ファイルのバイナリ ソースを使用すると、次のエラーが表示されます。

Pushing NuGet config to {url} failed. Use --debug for more information.

このエラーは、vcpkg が NuGet コマンド ラインを使用してパッケージを NuGet フィードにアップロードしようとしたときに発生します。

原因 1: ユーザーの書き込みアクセス許可が不十分である

次のエラー メッセージが表示されます。

System.Net.Http.HttpRequestException: Response status code does not indicate success: 403 (Forbidden - User <user> lacks permission to complete this action. You need to have 'AddPackage'.

ユーザーに十分な書き込みアクセス許可がないため、リモート ソースによってプッシュが拒否されました。

  • ユーザーまたはユーザー グループに書き込みアクセス許可があることを確認します。 NuGet では、ユーザーはフィードに対して少なくとも Contributor ロール である必要があります。

原因 2: NuGet フィードの URL が正しく構成されていません

次のエラーが表示されることがあります。

System.Net.Http.HttpRequestException: Response status code does not indicate success: 405 (Method Not Allowed).

要求メソッドを認識しなかったため、サーバーは NuGet のプッシュ要求を拒否しました。

  • バイナリ ソースの URI が正しいこと、およびフィードのサービス インデックス (通常は <feed base url>/nuget/v3/index.json) に転送されることを確認します。

その他の NuGet リソース

NuGet フィードへの接続と発行に関するガイドラインについてはNuGet のドキュメントを参照してください。

キャッシュ アップロード エラー

重要

vcpkg ツールを最新リリースに更新します。 さらに、包括的なエラー ログの デバッグ出力 を有効にします。

バイナリ パッケージをキャッシュにアップロードするときにエラーが発生しました。

原因 1: バイナリ キャッシュ プロバイダーのアップロードに失敗しました

アップロードはさまざまな理由で失敗する可能性があり、通常、エラー メッセージはプロバイダー固有です。

  • キャッシュに対して認証されていることを確認します。 異なるプロバイダーの認証方法が異なります。
  • キャッシュに適切な URI が指定されているかどうかを確認します。
  • バイナリ ソースとして NuGet を使用している場合は、「 push のトラブルシューティング を参照してください。
  • 特定のプロバイダーのドキュメントまたはトラブルシューティング ガイドを確認します。

空のバイナリ キャッシュ

重要

vcpkg ツールを最新リリースに更新します。 さらに、包括的なエラー ログの デバッグ出力 を有効にします。

エラーは発生せず、vcpkg のインストールは成功しましたが、バイナリ キャッシュは空のままです。 エラーが発生した場合は、NuGet のトラブルシューティング push を参照し 他のプロバイダーのトラブルシューティング アップロードしてください。

原因 1: vcpkg にバイナリ キャッシュへの書き込みアクセス許可がない

出力に次のメッセージがありません。

Uploading binaries for 'rapidjson:x64-windows' to <binary source> source <url>.
Stored binaries in 1 destinations in 1.5 s.

vcpkg はバイナリ パッケージのバイナリ キャッシュへのアップロードをスキップしました。

リモート バイナリ キャッシュを使用する代わりにライブラリを再構築する

重要

vcpkg ツールを最新リリースに更新します。 さらに、包括的なエラー ログの デバッグ出力 を有効にします。

必要なバイナリ パッケージがリモート バイナリ キャッシュで使用できる場合でも、システムはライブラリをローカルに再構築します。

出力に次のメッセージがありません。

Restored 1 package(s) from <remote binary cache> in 1.1 s. Use --debug to see more details.

原因 1: vcpkg にリモート バイナリ キャッシュからの読み取りアクセス許可がない

vcpkg は、リモート キャッシュ経由で既定のバイナリ キャッシュを読み取るために選択します。

原因 2: リモート バイナリ キャッシュが空です

リモート キャッシュには、プッシュしたバイナリ パッケージの一覧が含まれている必要があります。

原因 3: ローカルビルド環境とリモートビルド環境の違い

バイナリ キャッシュ内の各パッケージには、バイナリ パッケージを区別するためのコンパイラ バージョン、ソース、およびその他の情報を含む ABI ハッシュ でラベルが付けられます。 ローカルで計算された ABI ハッシュがリモートに格納されているハッシュと一致しない場合、パッケージは取得されません。

予期しない、または頻繁にライブラリを再構築する

重要

vcpkg ツールを最新リリースに更新します。 さらに、包括的なエラー ログの デバッグ出力 を有効にします。

変更されていない環境では、vcpkg を更新せずに、ライブラリを一時的に再構築していることがわかります。

原因 1: ビルド環境で検出されない変更

バイナリ キャッシュ内の各パッケージには、バイナリ パッケージを区別するためのコンパイラ バージョン、ソース、およびその他の情報を含む ABI ハッシュ でラベルが付けられます。 ローカルで計算された ABI ハッシュがリモートに格納されているハッシュと一致しない場合、パッケージは取得されません。

ABI ハッシュの不一致のトラブルシューティング

重要

vcpkg ツールを最新リリースに更新します。 さらに、包括的なエラー ログの デバッグ出力 を有効にします。

このガイドは、同じ名前の 2 つのバイナリ パッケージに対して異なる ABI ハッシュがある理由をユーザーが診断することを目的としています。

2 つのバイナリ パッケージの比較

同じ名前の 2 つのパッケージの違いを判断するには、ソース、ツール バージョン、コンパイラ、ターゲット プラットフォームなど、さまざまなデータを比較する必要があります。 ABI ハッシュは、このデータの簡潔な表現を提供します。 ABI ハッシュを計算する場合、vcpkg は、ファイルの内容、ツールのバージョン、システムの詳細など、関連するすべてのデータを考慮します。 各データ ポイントのハッシュを作成し、これらのハッシュをバイナリ パッケージの 1 つの値に結合します。

バイナリ パッケージ ABI ハッシュの比較

ライブラリ zlib の ABI ハッシュ は bb1c96759ac96102b4b18215db138daedd3eb16c2cd3302ae7bffab2b643eb87。

[DEBUG] Trying to hash <path>\buildtrees\zlib\x86-windows.vcpkg_abi_info.txt
[DEBUG] <path>\buildtrees\zlib\x86-windows.vcpkg_abi_info.txt has hash bb1c96759ac96102b4b18215db138daedd3eb16c2cd3302ae7bffab2b643eb87

同じライブラリの実行間でハッシュが変更された場合、これは 2 つのパッケージが異なっていることを示します。

コンパイラ バージョン ABI ハッシュの比較

実行の間にコンパイラのバージョンが変更されたかどうかを確認します。

[DEBUG] -- The C compiler identification is MSVC 19.36.32538.0
[DEBUG] -- The CXX compiler identification is MSVC 19.36.32538.0
[DEBUG] #COMPILER_HASH#f5d02a6542664cfbd4a38db478133cbb1a18f315

コンパイラ ハッシュが f5d02a6542664cfbd4a38db478133cbb1a18f315。

ABI ハッシュ エントリの比較

各パッケージの ABI エントリを比較します。 エントリは、最終的なハッシュに寄与する情報の一部を表します。

[DEBUG] <abientries for zlib:x86-windows>
[DEBUG]   0001-Prevent-invalid-inclusions-when-HAVE_-is-set-to-0.patch|750b9542cb55e6328cca01d3ca997f1373b9530afa95e04213168676936e7bfa
[DEBUG]   0002-skip-building-examples.patch|835ddecfed752e0f49be9b0f8ff7ba76541cb0a150044327316e22ca84f8d0c2
[DEBUG]   0003-build-static-or-shared-not-both.patch|d6026271dcb3d8fc74b41e235620ae31576a798e77aa411c3af8cd9e948c02b1
[DEBUG]   0004-android-and-mingw-fixes.patch|37a43eddbcb1b7dde49e7659ae895dfd0ff1df66666c1371ba7d5bfc49d8b438
[DEBUG]   cmake|3.26.2
[DEBUG]   features|core
[DEBUG]   portfile.cmake|ac63047b644fa758860dd7ba48ff9a13b058c6f240b8e8d675b8fbba035976be
[DEBUG]   ports.cmake|5a8e00cedff0c898b1f90f7d129329d0288801bc9056562b039698caf31ff3f3
[DEBUG]   post_build_checks|2
[DEBUG]   powershell|7.3.6
[DEBUG]   triplet|x86-windows
[DEBUG]   triplet_abi|3e71dd1d4afa622894ae367adbbb1ecbd42c57c51428a86b675fa1c8cad3a581-36b818778ba6f2c16962495caedb9a7b221d5be4c60de1cd3060f549319a9931-f5d02a6542664cfbd4a38db478133cbb1a18f315
[DEBUG]   usage|be22662327df993eebc437495add75acb365ab18d37c7e5de735d4ea4f5d3083
[DEBUG]   vcpkg-cmake|1b3dac4b9b0bcbef227c954b495174863feebe3900b2a6bdef0cd1cf04ca1213
[DEBUG]   vcpkg-cmake-wrapper.cmake|5d49ef2ee6448479c2aad0e5f732e2676eaba0411860f9bebabe6002d66f57d1
[DEBUG]   vcpkg.json|bc94e2540efabe36130a806381a001c57194e7de67454ab7ff1e30aa15e6ce23
[DEBUG]   vcpkg_copy_pdbs|d57e4f196c82dc562a9968c6155073094513c31e2de475694143d3aa47954b1c
[DEBUG]   vcpkg_fixup_pkgconfig|588d833ff057d3ca99c14616c7ecfb5948b5e2a9e4fc02517dceb8b803473457
[DEBUG]   vcpkg_from_git|8f27bff0d01c6d15a3e691758df52bfbb0b1b929da45c4ebba02ef76b54b1881
[DEBUG]   vcpkg_from_github|b743742296a114ea1b18ae99672e02f142c4eb2bef7f57d36c038bedbfb0502f
[DEBUG]   vcpkg_replace_string|d43c8699ce27e25d47367c970d1c546f6bc36b6df8fb0be0c3986eb5830bd4f1
[DEBUG] </abientries>

Note

triplet_abi エントリには、x86-windows トリプレットのファイル コンテンツのハッシュ、windows.cmake ツールチェーン、コンパイラ ハッシュの 3 つのハッシュが含まれています。 これらのハッシュは、別のプラットフォームをターゲットにすることを決定した場合に変更されます。

不一致 1: ポート ファイル

ポート ファイルには、ポート スクリプト (portfile.cmake、 vcpkg.json)、パッチ ファイル (*.patch)、またはポート ディレクトリ内のその他のファイル ( ports/<library>/*) が含まれます。

原因 1: CI またはパイプラインによってポート レジストリが更新されました

CI で vcpkg が実行される前に、最新の vcpkg リポジトリが複製されました。

  • git clone https://github.com/microsoft/vcpkgの後にbootstrapスクリプトを使用する場合は、特定のコミットにチェックアウトしてください。
  • vcpkg を git サブモジュールとしてプロジェクトに追加することを検討してください。

原因 2: GitHub Actions が vcpkg を更新しました

GitHub Actions によって提供された vcpkg のシステム コピーを使用しています。これは更新されました。

  • vcpkg の独自のコピーを複製します。
  • プロジェクトで vcpkg を git サブモジュールにすることを検討してください。

不一致 2: vcpkg CMake ヘルパー関数

CMake ヘルパー関数は、スクリプト ディレクトリ ( scripts/*) に存在し、通常は vcpkg_ で始まります。

原因 1: CI またはパイプラインの更新されたヘルパー スクリプト

CI で vcpkg が実行される前に、最新の vcpkg リポジトリが複製されました。

  • git clone https://github.com/microsoft/vcpkgの後にbootstrapスクリプトを使用する場合は、特定のコミットにチェックアウトしてください。
  • vcpkg を git サブモジュールとしてプロジェクトに追加することを検討してください。

原因 2: GitHub Actions が vcpkg を更新しました

GitHub Actions によって提供された vcpkg のシステム コピーを使用しています。これは更新されました。

  • vcpkg の独自のコピーを複製します。
  • プロジェクトで vcpkg を git サブモジュールにすることを検討してください。

不一致 3: コンパイラのバージョン

vcpkg は、別のバージョンのコンパイラを使用して依存関係を再構築しました。

原因 1: Visual Studio C++ コンパイラが自動的に更新されます。

Visual Studio は、実行の間にコンパイラを含む C++ ワークロードを自動的に更新しました。 マイナー バージョンの更新でも、vcpkg によってライブラリのセットが再構築されます。

原因 2: ライブラリは、使用に使用したコンピューターとは異なるコンピューター上に構築されました。

1 台のコンピューターがバイナリ パッケージを作成し、リモート キャッシュに発行しました。 通常、開発に使用される別のマシンは、キャッシュされたライブラリを使用しました。

  • リモート コンピューターと同じ C++ コンパイラ バージョンをローカルで使用します。 Visual Studio の場合は、 修正バージョンのブートストラップを検討してください。
  • 開発目的で依存関係をローカルに再構築します。 継続的インテグレーション中に後で問題をテストして対処します。

原因 3: セルフホステッド イメージによってコンパイラが更新されました。

vcpkg 依存関係のビルドに使用した基になるイメージが変更され、コンパイラのバージョンが更新されました。

  • 安定したバージョン管理されたイメージにピン留めします。 実行の間に基になるツールまたはコンパイラが自動的に更新されないように、最新のイメージをフェッチしていないことを確認します。
  • イメージを頻繁に更新する必要がある場合は、イメージの作成時に C++ コンパイラ ツールを特定のバージョンにピン留めします。

原因 4: GitHub Hosted Runners によって基になるコンパイラが更新されました。

ホストされている GitHub ランナーは、コンパイラとツールを毎週更新します。

  • 現時点では、イメージを修正し、ツールとコンパイラのバージョンが定期的に更新されないようにする方法はありません。 代替ソリューションについては、 その他のオプション セクションを参照してください。

不一致 4: 実行の間に変更されたツールのバージョン。

ライブラリ (CMake または PowerShell) のビルドに使用されるツールのバージョンが、実行の間に変更されました。

原因 1: Visual Studio が自動的に更新されました。

Visual Studio は、実行の間に、ツールを含めて自動的に更新されます。 マイナー バージョンの更新でも、vcpkg によってライブラリのセットが再構築されます。

  • Visual Studio の自動更新を無効にする。
  • vcpkg 呼び出しに --x-abi-tools-use-exact-versions を追加します。 これにより、 vcpkgTools.xmlのバージョンに基づいてツールの ABI が修正されます。vcpkg は必要に応じて独自のコピーをフェッチします。

原因 2: ライブラリは、使用に使用したコンピューターとは異なるコンピューター上に構築されました。

1 台のコンピューターがバイナリ パッケージを作成し、リモート キャッシュに発行しました。 通常、開発に使用される別のマシンは、キャッシュされたライブラリを使用しました。

  • リモート コンピューターと同じツール バージョンをローカルで使用します。
  • 開発目的で依存関係をローカルに再構築します。 継続的インテグレーション中に後で問題をテストして対処します。
  • vcpkg 呼び出しに --x-abi-tools-use-exact-versions を追加します。 これにより、 vcpkgTools.xmlのバージョンに基づいてツールの ABI が修正されます。vcpkg は必要に応じて独自のコピーをフェッチします。

原因 3: セルフホステッド イメージによってツールが更新されました。

vcpkg 依存関係のビルドに使用した基になるイメージが変更されました。これは、使用されているツールのバージョンです。

  • 安定したバージョン管理されたイメージにピン留めします。 実行の間に基になるツールが自動的に更新されないように、最新のイメージをフェッチしていないことを確認します。
  • イメージを頻繁に更新する必要がある場合は、イメージの作成時に関連するツールを特定のバージョンにピン留めします。
  • vcpkg 呼び出しに --x-abi-tools-use-exact-versions を追加します。 これにより、 vcpkgTools.xmlのバージョンに基づいてツールの ABI が修正されます。vcpkg は必要に応じて独自のコピーをフェッチします。

原因 4: GitHub ホストランナーが基になるツールを更新しました。

ホストされている GitHub ランナーは、コンパイラとツールを毎週更新します。

  • vcpkg 呼び出しに --x-abi-tools-use-exact-versions を追加します。 これにより、 vcpkgTools.xmlのバージョンに基づいてツールの ABI が修正されます。vcpkg は必要に応じて独自のコピーをフェッチします。

その他のオプション

上記のオプションが機能しない場合は、次の回避策を検討してください。

  • vcpkg exportを使用して、マニフェストから依存関係を復元するのではなく、依存関係のスタンドアロン アーカイブを生成します。
  • Docker セルフホステッド イメージを使用してライブラリをビルドすることを検討する
  • vcpkg ライブラリを定期的にビルドする補助的な継続的インテグレーションを実行する (毎日または毎週など)

問題がこの一覧に含まれていない

問題がここに記載されていない場合は、リポジトリにアクセスして新しい問題を作成してください。