バイナリ キャッシュの構成
構成構文
バイナリ キャッシュは、環境変数 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 キャッシュを使用します。 |
x-az-universal,<organization>,<project>,<feed>[,<rw>] |
試験段階: 警告なしに変更または削除されます ソースとして Azure Artifacts のユニバーサル パッケージを使用します。 |
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"
Azure Artifacts のユニバーサル パッケージ
Note
このセクションでは、いつでも変更または削除できる vcpkg の試験的な機能について説明します。
x-az-universal,<organization>,<project>,<feed>[,<rw>]
Azure Artifacts Universal Packages をプロバイダーとして追加します。
クイックスタート
まず、ユニバーサル パッケージ フィードを作成する必要があります。 手順については、 Universal パッケージのクイックスタート を参照してください。
次に、Azure CLI をインストールして認証する必要があります。 手順については、Azure CLI への 認証ガイド を参照してください。 vcpkg はこのコマンド ライン ツールを使用するため、実行可能ファイルの検索パスに含まれていることを確認します。
例:
x-az-universal,organization_url,project_name,feed_name,readwrite
project_name
パラメーターを指定して、vcpkg をダウンロードし、プロジェクト スコープでユニバーサル パッケージをフィードに発行します。
x-az-universal,organization_url,,feed_name,readwrite
vcpkg をダウンロードし、組織のスコープでフィードに発行するには、 project_name
パラメーターを空のままにします。
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 つのハッシュが含まれています。 これらのハッシュは、別のプラットフォームをターゲットにすることを決定した場合に変更されます。
vcpkg