バイナリキャッシュリファレンス

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

構成構文

バイナリキャッシュは、環境変数 VCPKG_BINARY_SOURCES ( <source>;<source>;... に設定) とコマンドラインオプション --binarysource=<source>で構成されます。オプションは、最初に環境から評価され、次にコマンドラインから評価されます。バイナリキャッシュは、最後のコマンドラインオプションとして --binarysource=clear を渡すことによって完全に無効にすることができます。

Form	説明
`clear`	以前のすべてのソースを無効にする (既定値を含む)
`default[,<rw>]`	既定の files プロバイダーを追加します
`files,<absolute path>[,<rw>]`	ファイルベースの場所を追加します
`nuget,<uri>[,<rw>]`	NuGet ベースのソースを追加します。NuGet CLI の `-Source` パラメーターと同等
`nugetconfig,<path>[,<rw>]`	NuGet-config-file ベースのソースを追加します。は、NuGet CLI の `-Config` パラメーターに相当します。
`nugettimeout,<seconds>`	NuGet ネットワーク操作のタイムアウトを指定します。は、NuGet CLI の `-Timeout` パラメーターに相当します。
`http,<url_template>[,<rw>[,<header>]]`	カスタム http ベースの場所を追加します。
`x-azblob,<baseuri>,<sas>[,<rw>]`	試験段階: 警告なしに変更または削除されます Shared Access Signature を使用して Azure Blob Storage ソースを追加する
`x-gcs,<prefix>[,<rw>]`	試験段階: 警告なしに変更または削除されます Google Cloud Storage (GCS) ソースを追加します。
`x-aws,<prefix>[,<rw>]`	試験段階: 警告なしに変更または削除されます AWS S3 ソースを追加します。
`x-aws-config,<parameter>`	試験段階: 警告なしに変更または削除されますすべての AWS S3 プロバイダーを構成します。
`x-cos,<prefix>[,<rw>]`	試験段階: 警告なしに変更または削除されます Tencent Cloud Object Storage ソースを追加します。
`x-gha,<rw>]`	試験段階: 警告なしに変更または削除されますソースとして GitHub Actions キャッシュを使用します。
`interactive`	NuGet の対話型資格情報管理を有効にします (デバッグ用。コマンドラインで`--debug`が必要)

特定のソース <rw> 省略可能なパラメーターは、バイナリのダウンロード用に参照される (read)(既定)、オンデマンドビルドをそのリモート (write)、またはその両方 (readwrite) にアップロードするかどうかを制御します。

プロバイダー

AWS S3 プロバイダー

Note

このセクションでは、いつでも変更または削除できる vcpkg の試験的な機能について説明します。

x-aws,<prefix>[,<rw>]

AWS CLI を使用して AWS S3 ソースを追加します。 <プレフィックス> は s3:// で始まり、 /で終わる必要があります。

x-aws-config,no-sign-request

--no-sign-requestを AWS CLI に渡します。

Azure Blob Storage プロバイダー

Note

このセクションでは、いつでも変更または削除できる vcpkg の試験的な機能について説明します。

x-azblob,<baseuri>,<sas>[,<rw>]

Shared Access Signature 検証を使用して Azure Blob Storage プロバイダーを追加します。 <baseuri> には、コンテナーパスを含める必要があります。

クイックスタート

まず、Azure ストレージアカウントとコンテナーを作成する必要があります。手順については、 Azure Storage クイックスタートのドキュメントを参照してください。

次に、 Shared Access Signature (SAS) を作成する必要があります。これは、ストレージアカウントから Settings ->Shared Access Signature で実行できます。この SAS には次のものが必要です。

許可されるサービス: Blob
許可されるリソースの種類: Object
許可されるアクセス許可: Read ( read を使用している場合) または Read、Create ( write または readwrite を使用している場合)

BLOB エンドポイントとコンテナーを <baseuri> として渡し、 ? プレフィックスのない生成された SAS を <sas>として渡す必要があります。

例:

x-azblob,https://<storagename>.blob.core.windows.net/<containername>,sv=2019-12-12&ss=b&srt=o&sp=rcx&se=2020-12-31T06:20:36Z&st=2020-12-30T22:20:36Z&spr=https&sig=abcd,readwrite

vcpkg は、通常の操作中に SAS が表示されないようにしようとしますが、次のようになります。

--debugが渡されると、完全に印刷されます
これは、コマンドラインパラメーターとしてサブプロセスに渡されます。次に例を示します。 curl.exe

Azure Blob Storage には、特定の日数でアクセスされていないキャッシュエントリを削除する機能が含まれています。これは、バイナリキャッシュのサイズを自動的に管理するために使用できます。詳細については、「 Data Lifecycle Management on Microsoft Docs 」を参照するか、ストレージアカウントの Azure Portal で Data management ->Lifecycle management を探します。

Tencent Cloud Object Storage プロバイダー

Note

このセクションでは、いつでも変更または削除できる vcpkg の試験的な機能について説明します。

x-cos,<prefix>[,<rw>]

COS ソースを追加します。 <prefix> は cos:// で始まり、 /で終わる必要があります。

ファイルプロバイダー

files,<absolute path>[,<rw>]

binary キャッシュ ID に基づいて、zip 圧縮アーカイブをパスに格納します。

Google Cloud Storage プロバイダー

Note

このセクションでは、いつでも変更または削除できる vcpkg の試験的な機能について説明します。

x-gcs,<prefix>[,<rw>]

Google Cloud Storage プロバイダーを追加します。 <prefix> は gs:// で始まり、 /で終わる必要があります。

クイックスタート

まず、Google Cloud Platform アカウントとストレージバケット (GCS クイックスタート] を作成する必要があります。

このクイックスタートの一環として、google Cloud で認証するように gsutil コマンドラインツールを構成しました。 vcpkg はこのコマンドラインツールを使用するため、実行可能ファイルの検索パスに含まれていることを確認します。

例 1 (オブジェクトに共通のプレフィックスのないバケットを使用):

x-gcs,gs://<bucket-name>/,readwrite

例 2 (オブジェクトにバケットとプレフィックスを使用):

x-gcs,gs://<bucket-name>/my-vcpkg-cache/maybe/with/many/slashes/,readwrite
x-gcs,gs://<bucket-name>/my-vcpkg-cache/maybe/with`,commas/too!/,readwrite

コンマ (,) は、GCS のオブジェクトプレフィックスの一部として有効です。前の例に示すように、vcpkg 構成でエスケープすることを忘れないでください。 GCS にはフォルダーがありません (一部の GCS ツールはフォルダーをシミュレートします)。 vcpkg キャッシュで使用されるプレフィックスを作成したり、操作したりする必要はありません。

GitHub Actions キャッシュ

Note

このセクションでは、いつでも変更または削除できる vcpkg の試験的な機能について説明します。

x-gha[,<rw>]

GitHub Actions キャッシュをプロバイダーとして追加します。このバイナリキャッシュプロバイダーは、GitHub Actions ワークフローのコンテキストでのみ有効です。このプロバイダーでは、 ACTIONS_CACHE_URL と ACTIONS_RUNTIME_TOKEN の両方の環境変数を設定する必要があります。これらの環境変数を正しく設定する方法については、次のクイックスタートセクションで説明します。

クイックスタート

vcpkg で GitHub Actions Cache を使用するには、Actions Cache の URL とランタイムトークンが必要です。これを行うには、次のようなワークフローステップで両方の値を環境変数としてエクスポートする必要があります。

- 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 || '');

これらの値を vcpkg コマンドライン引数の代わりに環境変数として指定することは、GitHub Actions Cache バイナリキャッシュプロバイダーが GitHub Actions ワークフローからのみ使用できるため、仕様上です。

環境変数がエクスポートされたら、次のように GitHub Actions バイナリキャッシュプロバイダーを使用して vcpkg を実行できます。

- name: Install dependencies via vcpkg
  run: vcpkg install zlib --binarysource="clear;x-gha,readwrite"

HTTP プロバイダー

http,<url_template>[,<rw>[,<header>]]

各バイナリキャッシュ操作は、HTTP 動詞にマップされます。

ダウンロード- GET
アップロード- PUT
存在の確認 - HEAD

URL テンプレート

テンプレートでは、変数の展開に中かっこを使用します。変数 'name'、'version'、'sha'、および 'triplet' を使用できます。次に例を示します。

https://cache.example.com/{name}/{version}/{sha}

警告

この値は、外部プロセス呼び出しのコマンドラインに表示される場合があり、環境にセキュリティ上の影響を与える可能性があります。

認証は、HTTP Authorization ヘッダーを指定することでサポートされます。次に例を示します。

http,https://cache.example.com/{name}/{version}/{sha},readwrite,Authorization: Bearer BearerTokenValue

NuGet プロバイダー

-Source NuGet CLI パラメーターを使用して NuGet サーバーを追加します。

nuget,<uri>[,<rw>]

-Config NuGet CLI パラメーターで NuGet 構成ファイルを使用します。

nugetconfig,<path>[,<rw>]

NuGet ソースのタイムアウトを構成します。

nugettimeout,<seconds>

構成ファイルでは、フィードへのパッケージの書き戻しをサポートする defaultPushSource を定義する必要があります。

資格情報

多くの NuGet サーバーでは、アクセスするために追加の資格情報が必要です。資格情報を提供する最も柔軟な方法は、カスタム nuget.config ファイルを含むnugetconfig ソースを使用することです。詳細については、「認証されたフィードからのパッケージの管理」を参照してください。

ただし、NuGet の組み込み資格情報プロバイダーを使用するか、環境の既定の nuget.configをカスタマイズして、多くのサーバーに対して認証を行うこともできます。既定の構成は、次のような nuget クライアント呼び出しを介して拡張できます。

nuget sources add -Name MyRemote -Source https://... -Username $user -Password $pass

その後、 nuget,MyRemote,readwrite経由で vcpkg に渡されます。 vcpkg によって使用される NuGet の正確なコピーへのパスを取得するには、 vcpkg fetch nugetを実行すると、次のようなレポートが表示されます。

$ vcpkg fetch nuget
/vcpkg/downloads/tools/nuget-5.5.1-linux/nuget.exe

Windows 以外のユーザーは、 mono /path/to/nuget.exe sources add ...経由で mono を使用してこれを呼び出す必要があります。

`metadata.repository`

nugetおよびnugetconfigソースプロバイダーは、nuget パッケージを生成する際に特定の環境変数を考慮します。パッケージの metadata.repository フィールドは、次のように生成されます。

    <repository type="git" url="${VCPKG_NUGET_REPOSITORY}"/>

または

    <repository type="git"
                url="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}.git"
                branch="${GITHUB_REF}"
                commit="${GITHUB_SHA}"/>

適切な環境変数が定義され、空でない場合は >。これは、GitHub Packages のパッケージを building プロジェクトに関連付けるために特に使用され、元のパッケージソースに関連付けるものではありません。

NuGet キャッシュ

NuGet のユーザー全体のキャッシュは、既定では使用されません。すべての nuget ベースのソースで使用するには、 environment 変数VCPKG_USE_NUGET_CACHE を true (大文字と小文字を区別しない) または 1に設定します。

プロバイダーの例

選択した CI システムが一覧にない場合は、PR を送信して追加できます。

GitHub Packages

GitHub Packages で vcpkg を使用するには、 NuGet プロバイダーを使用することをお勧めします。

Note

2020-09-21: GitHub のホストされているエージェントには、最新のバイナリキャッシュをサポートしていないパスに、以前にインストールされた vcpkg のコピーが付属しています。つまり、パスプレフィックスのない bootstrap-vcpkg または vcpkg を直接呼び出すと、意図しない vcpkg インスタンスが呼び出される可能性があります。 vcpkg の独自のコピーを使用する場合は、vcpkg の独自のコピーを使用する場合の問題を回避するために、次の 2 つの手順を実行します。

shell: 'bash'を使用して、同等のrm -rf "$VCPKG_INSTALLATION_ROOT"を実行します。
./vcpkg、vcpkg/vcpkg、.\bootstrap-vcpkg.batなど、常にパスプレフィックスを使用してvcpkgとbootstrap-vcpkgを呼び出します。

# actions.yaml
#
# In this example, vcpkg has been added as a submodule (`git submodule add https://github.com/Microsoft/vcpkg`).
env:
  VCPKG_BINARY_SOURCES: 'clear;nuget,GitHub,readwrite'

matrix:
  os: ['windows-2019', 'ubuntu-20.04']
  include:
    - os: 'windows-2019'
      triplet: 'x86-windows'
      mono: ''
    - os: 'ubuntu-20.04'
      triplet: 'x64-linux'
      # To run `nuget.exe` on non-Windows platforms, `mono` must be used.
      mono: 'mono'

steps:
  # This step assumes `vcpkg` has been bootstrapped (run `./vcpkg/bootstrap-vcpkg`)
  - name: 'Setup NuGet Credentials'
    shell: 'bash'
    # Replace <OWNER> with your organization name
    run: |
      ${{ matrix.mono }} `./vcpkg/vcpkg fetch nuget | tail -n 1` \
        sources add \
        -source "https://nuget.pkg.github.com/<OWNER>/index.json" \
        -storepasswordincleartext \
        -name "GitHub" \
        -username "<OWNER>" \
        -password "${{ secrets.GITHUB_TOKEN }}"
      ${{ matrix.mono }} `./vcpkg/vcpkg fetch nuget | tail -n 1` \
        setapikey "${{ secrets.GITHUB_TOKEN }}" \
        -source "https://nuget.pkg.github.com/<OWNER>/index.json"

  # Omit this step if you're using manifests
  - name: 'vcpkg package restore'
    shell: 'bash'
    run: >
      ./vcpkg/vcpkg install sqlite3 cpprestsdk --triplet ${{ matrix.triplet }}

manifestsを使用している場合は、vcpkg package restoreの手順を省略できます。これはビルドの一部として自動的に実行されます。

詳細については、 GitHub Packages の NuGet ドキュメントを参照してください。

Azure DevOps Artifacts

Azure DevOps Artifacts で vcpkg を使用するには、 NuGet プロバイダーを使用することをお勧めします。

まず、DevOps アカウントで Artifacts が有効になっていることを確認します。管理者は、 Project Settings ->General ->Overview ->Azure DevOps Services>Artifacts を使用してこれを有効にすることができます。

次に、プロジェクトのフィードを作成します。フィード URL は、/nuget/v3/index.jsonで終わるhttps://リンクになります。詳細については、 Azure DevOps Artifacts のドキュメントを参照してください。

パイプラインからのフィードの使用

# azure-pipelines.yaml
variables:
- name: VCPKG_BINARY_SOURCES
  value: 'clear;nuget,<FEED_URL>,readwrite'

steps:
# Remember to add this task to allow vcpkg to upload archives via NuGet
- task: NuGetAuthenticate@0

Windows OS 以外のカスタムエージェントを使用している場合は、Mono をインストールして nuget.exe (apt install mono-complete、 brew install monoなど) を実行する必要があります。

フィードをローカルで使用する

# On Windows Powershell
PS> & $(vcpkg fetch nuget | select -last 1) sources add `
  -name ADO `
  -Source https://pkgs.dev.azure.com/$ORG/_packaging/$FEEDNAME/nuget/v3/index.json `
  -Username $USERNAME `
  -Password $PAT
PS> $env:VCPKG_BINARY_SOURCES="nuget,ADO,readwrite"

# On Linux or OSX
$ mono `vcpkg fetch nuget | tail -n1` sources add \
  -name ADO \
  -Source https://pkgs.dev.azure.com/$ORG/_packaging/$FEEDNAME/nuget/v3/index.json \
  -Username $USERNAME \
  -Password $PAT
$ export VCPKG_BINARY_SOURCES="nuget,ADO,readwrite"

セキュリティを最大限に高めるパスワードとして、個人用アクセストークン (PAT) を使用します。 PAT は、 User Settings ->Personal Access Tokens または https://dev.azure.com/<ORG>/_usersSettings/tokens で生成できます。

ABI ハッシュ

Note

ABIハッシュに関する情報は実装上の注意事項として提供されており、予告なしに変更されます。

すべてのビルドについて、vcpkg は ABI ハッシュ を計算して等価性を判断します。 2 つのビルドに同じ ABI ハッシュがある場合、vcpkg はそれらを同一と見なし、プロジェクトとマシン間でバイナリを再利用します。

ABI ハッシュでは、次の点が考慮されます。

ポートディレクトリ内のすべてのファイル
トリプレットファイルの内容と名前
C++ コンパイラ実行可能ファイル
C コンパイラ実行可能ファイル
選択されているのセット
各依存関係の ABI ハッシュ
portfile.cmakeによって参照されるすべてのヘルパー関数 (ヒューリスティック)
使用される CMake のバージョン
次に示す環境変数の内容 VCPKG_ENV_PASSTHROUGH
ツールチェーンファイルのテキストコンテンツ (VCPKG_CHAINLOAD_TOOLCHAIN_FILE)
GRDK ツールキット (Xbox プラットフォームをターゲットにしている場合のみ)

この広範なリストにもかかわらず、キャッシュを倒し、非決定的性を導入する可能性があります。環境に合わせて追跡する必要がある追加の詳細がある場合は、コメントに追加情報を含むトリプレットファイルを生成できます。その追加情報は ABI ハッシュに含まれており、バイナリの一意のユニバースを確保します。

.DS_Storeという名前のファイルは、ABI ハッシュとは見なされません。

計算された ABI ハッシュは、検査のために各パッケージと現在インストールされているディレクトリの /share/<port>/vcpkg_abi_info.txt に格納されます。

zlib の ABI ハッシュの例

debug 出力を有効にして pacakge の完全なアプリケーションバイナリインターフェイス (ABI) ハッシュを出力します。 zlib の場合:

[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

パッケージ zlib の ABI ハッシュbb1c96759ac96102b4b18215db138daedd3eb16c2cd3302ae7bffab2b643eb87 は、バイナリパッケージを区別するために、可能なすべての関連情報をハッシュすることによって構築されます。

コンパイラのバージョンは 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

関連するファイル、コンパイラ、ツールのバージョン情報がハッシュされ、最終的な 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 つのハッシュが含まれています。これらのハッシュは、別のプラットフォームをターゲットにすることを決定した場合に変更されます。

次の方法で共有

バイナリキャッシュリファレンス

構成構文

プロバイダー

AWS S3 プロバイダー

Azure Blob Storage プロバイダー

クイックスタート

Tencent Cloud Object Storage プロバイダー

ファイルプロバイダー

Google Cloud Storage プロバイダー

クイックスタート

GitHub Actions キャッシュ

クイックスタート

HTTP プロバイダー

URL テンプレート

ヘッダー

NuGet プロバイダー

資格情報

`metadata.repository`

NuGet キャッシュ

プロバイダーの例

GitHub Packages

Azure DevOps Artifacts

パイプラインからのフィードの使用

フィードをローカルで使用する

ABI ハッシュ

zlib の ABI ハッシュの例

フィードバック

その他のリソース

次の方法で共有

バイナリ キャッシュリファレンス

構成構文

プロバイダー

AWS S3 プロバイダー

Azure Blob Storage プロバイダー

クイックスタート

Tencent Cloud Object Storage プロバイダー

ファイル プロバイダー

Google Cloud Storage プロバイダー

クイックスタート

GitHub Actions キャッシュ

クイックスタート

HTTP プロバイダー

URL テンプレート

ヘッダー

NuGet プロバイダー

資格情報

metadata.repository

NuGet キャッシュ

プロバイダーの例

GitHub Packages

Azure DevOps Artifacts

パイプラインからのフィードの使用

フィードをローカルで使用する

ABI ハッシュ

zlib の ABI ハッシュの例

フィードバック

その他のリソース

バイナリキャッシュリファレンス

ファイルプロバイダー

`metadata.repository`