二進位快取組態

發行項
10/30/2024

組態語法

二進位快取已設定為環境變數 VCPKG_BINARY_SOURCES （設定為 <source>;<source>;...）和命令列選項 --binarysource=<source>。選項會先從環境評估，然後從命令行評估。藉由傳遞 --binarysource=clear 為最後一個命令行選項，即可完全停用二進位快取。

表單	描述
`clear`	停用所有先前的來源（包括預設值）
`default[,<rw>]`	新增預設檔案提供者
`files,<absolute path>[,<rw>]`	新增檔案型位置
`nuget,<uri>[,<rw>]`	新增以 NuGet 為基礎的來源;相當於 `-Source` NuGet CLI 的參數
`nugetconfig,<path>[,<rw>]`	新增 NuGet-config-file 型來源;相當於 `-Config` NuGet CLI 的參數。
`nugettimeout,<seconds>`	指定 NuGet 網路作業的逾時;相當於 `-Timeout` NuGet CLI 的參數。
`http,<url_template>[,<rw>[,<header>]]`	新增自訂 HTTP 型位置。
`x-azblob,<baseuri>,<sas>[,<rw>]`	實驗性：將變更或移除而不發出警告使用共用存取簽章新增 Azure Blob 儲存體來源
`x-gcs,<prefix>[,<rw>]`	實驗性：將變更或移除而不發出警告新增Google Cloud Storage （GCS）來源。
`x-aws,<prefix>[,<rw>]`	實驗性：將變更或移除而不發出警告新增 AWS S3 來源。
`x-aws-config,<parameter>`	實驗性：將變更或移除而不發出警告設定所有 AWS S3 提供者。
`x-cos,<prefix>[,<rw>]`	實驗性：將變更或移除而不發出警告新增騰訊雲端物件儲存來源。
`x-gha,<rw>]`	實驗性：將變更或移除而不發出警告使用 GitHub Actions 快取作為來源。
`x-az-universal,<organization>,<project>,<feed>[,<rw>]`	實驗性：將變更或移除而不發出警告使用 Azure Artifacts 中的通用套件作為來源。
`interactive`	開啟 NuGet 的互動式認證管理（用於偵錯;在命令行上需要`--debug`）

<rw>特定來源的選擇性參數會控制是否要查閱下載二進位檔（）（預設值）、隨選組建是否會上傳至該遠端或readwrite兩者（readwrite）。

提供者

AWS S3 提供者

注意

本節涵蓋 vcpkg 的實驗功能，隨時可能會變更或移除。

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

使用 AWS CLI 新增 AWS S3 來源。 <前置詞> 應該以開頭 s3:// ，並以結尾 /。

x-aws-config,no-sign-request

傳遞 --no-sign-request 至 AWS CLI。

Azure Blob 儲存體提供者

注意

本節涵蓋 vcpkg 的實驗功能，隨時可能會變更或移除。

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

使用共用存取簽章驗證新增 Azure Blob 儲存體提供者。 <baseuri> 應包含容器路徑。

快速入門

首先，您必須建立 Azure 儲存體帳戶和容器。如需指示，請參閱 Azure 儲存體快速入門檔。

接下來，您必須建立共用存取簽章（SAS），此簽章可以從 [設定 -> 共用存取簽章] 下的記憶體帳戶完成。此 SAS 需要：

允許的服務： Blob
允許的資源類型：物件
允許的權限：讀取（如果使用 read）或讀取、建立（如果使用 write 或 readwrite）

Blob 端點加上容器必須當做 <baseuri> 傳遞，而產生的 SAS 必須傳遞為，而沒有前置詞的 ? 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 儲存體包含一項功能，可移除在指定天數內尚未存取的快取專案，可用來自動管理二進位快取的大小。如需詳細資訊，請參閱 Microsoft Docs 上的數據生命週期管理，或在 Azure 入口網站中尋找 記憶體帳戶的數據管理 ->生命週期管理 。

騰訊雲端物件儲存提供者

注意

本節涵蓋 vcpkg 的實驗功能，隨時可能會變更或移除。

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

新增 COS 來源。 <prefix> 應該以開頭 cos:// ，並以結尾 /。

檔案提供者

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

根據二進位快取標識符，將 zip 壓縮封存儲存在路徑上。

Google Cloud Storage 提供者

注意

本節涵蓋 vcpkg 的實驗功能，隨時可能會變更或移除。

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

新增Google Cloud Storage提供者。 <prefix> 應該以開頭 gs:// ，並以結尾 /。

快速入門

首先，您必須建立Google雲端平台帳戶以及記憶體貯體（GCS 快速入門]。

在本快速入門中，您已將命令行工具設定 gsutil 為向Google Cloud 進行驗證。 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 快取

注意

本節涵蓋 vcpkg 的實驗功能，隨時可能會變更或移除。

x-gha[,<rw>]

將 GitHub Actions 快取新增為提供者。這個二進位快取提供者只有在 GitHub Actions 工作流程的內容中才有效。此提供者需要 ACTIONS_CACHE_URL 設定和 ACTIONS_RUNTIME_TOKEN 環境變數。下列快速入門一節涵蓋正確設定這些環境變數。

快速入門

為了讓 vcpkg 能夠使用 GitHub 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 快取二進位快取提供者只能從 GitHub Actions 工作流程使用。

匯出環境變數之後，可以使用 GitHub Actions 二進位快取提供者執行 vcpkg，如下所示：

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

Azure Artifacts 中的通用套件

注意

本節涵蓋 vcpkg 的實驗功能，隨時可能會變更或移除。

x-az-universal,<organization>,<project>,<feed>[,<rw>]

將 Azure Artifacts 中的通用套件新增為提供者。

快速入門

首先，您需要建立通用套件摘要。如需指示，請參閱通用套件快速入門。

接下來，您必須安裝並驗證 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

將 project_name 參數保留空白，讓 vcpkg 下載並將通用套件發佈至組織範圍的摘要。

HTTP 提供者

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

每個二進位快取作業都會對應至 HTTP 動詞命令：

下載- GET
上傳- PUT
檢查是否存在 - HEAD

URL 範本

此範本會使用大括弧進行變數展開。您可以使用變數 'name'、'version'、'sha' 和 'triplet'。例如：

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

警告

此值可能會出現在外部進程呼叫的命令行上，這可能會對您的環境造成安全性影響。

藉由指定 HTTP 授權標頭來支持驗證。例如：

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

NuGet 提供者

使用 NuGet CLI 參數新增 -Source NuGet 伺服器：

nuget,<uri>[,<rw>]

搭配 NuGet CLI 參數使用 NuGet 組態檔 -Config ：

nugetconfig,<path>[,<rw>]

設定 NuGet 來源的逾時：

nugettimeout,<seconds>

組態檔必須定義 defaultPushSource ，以支援將套件寫回摘要。

認證

許多 NuGet 伺服器需要額外的認證才能存取。提供認證的最彈性方式是透過 nugetconfig 來源與自定義 nuget.config 檔案。如需詳細資訊，請參閱從已驗證摘要取用套件。

不過，您仍然可以使用 NuGet 的內建認證提供者，或透過自定義環境的預設 nuget.config，對許多伺服器進行驗證。默認組態可以透過 nuget 用戶端呼叫來擴充，例如：

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

然後透過 nuget,MyRemote,readwrite傳遞至 vcpkg。您可以執行 vcpkg fetch nuget來取得 vcpkg 所使用之 NuGet 精確複本的路徑，這會報告類似下列內容：

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

非 Windows 用戶必須透過 mono /path/to/nuget.exe sources add ...透過單聲道呼叫此帳戶。

`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 中的套件與建置專案產生關聯，而不是要與原始套件來源產生關聯。

NuGet 快取

根據預設，不會使用 NuGet 的用戶範圍快取。若要針對每個以 nuget 為基礎的來源使用，請將環境變數VCPKG_USE_NUGET_CACHE 設定為 true （不區分大小寫）或 1。

提供者範例

如果未列出您選擇的 CI 系統，歡迎提交 PR 以新增它！

GitHub 套件

若要搭配 GitHub Packages 使用 vcpkg，建議使用 NuGet 提供者。

注意

2020-09-21：GitHub 裝載的代理程序隨附於不支援最新二進位快取之路徑上較舊且預安裝的 vcpkg 複本。這表示直接呼叫 bootstrap-vcpkg 或 vcpkg 沒有路徑前置詞，可能會呼叫非預期的 vcpkg 實例。如果您想要使用自己的 vcpkg 複本，下列兩個步驟可避免使用您自己的 vcpkg 複本時發生問題：

使用執行的 rm -rf "$VCPKG_INSTALLATION_ROOT" 對等專案 shell: 'bash'。
一律呼叫 vcpkg ，並使用 bootstrap-vcpkg 路徑前置詞，例如 ./vcpkg、 vcpkg/vcpkg、 .\bootstrap-vcpkg.bat等。

# 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 }}

如果您使用指令清單，可以省略 vcpkg package restore 步驟：它會在組建中自動執行。

如需詳細資訊，請參閱 GitHub Packages 的 NuGet 檔。

Azure DevOps Artifacts

若要搭配 Azure DevOps Artifacts 使用 vcpkg，建議使用 NuGet 提供者。

首先，請確定已在您的 DevOps 帳戶上啟用成品。系統管理員可以透過項目設定 - 一般 ->> 概觀 -> Azure DevOps Services>成品來啟用此功能。

接下來，為您的專案建立摘要。您的摘要 URL 將會是 https:// 結尾為 /nuget/v3/index.json的連結。如需詳細資訊，請參閱 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 作業系統，必須安裝 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）作為最大安全性的密碼。您可以在 [使用者設定 -> 個人存取令牌] 或 https://dev.azure.com/<ORG>/_usersSettings/tokens中產生 PAT。

ABI 哈希

注意

ABI 哈希的資訊會以實作注意事項的形式提供，而且不會通知變更。

針對每個組建，vcpkg 會 計算 ABI 哈希 以判斷等價。如果兩個組建具有相同的 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 哈希

啟用偵錯輸出，以列印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>

注意

專案 triplet_abi 包含三個哈希：三元組檔案內容的 x86-windows 哈希、 windows.cmake 工具鏈和編譯程式哈希。如果您決定以不同的平臺為目標，這些哈希將會變更。

共用方式為

二進位快取組態

組態語法

提供者

AWS S3 提供者

Azure Blob 儲存體提供者

快速入門

騰訊雲端物件儲存提供者

檔案提供者

Google Cloud Storage 提供者

快速入門

GitHub Actions 快取

快速入門

Azure Artifacts 中的通用套件

快速入門

HTTP 提供者

URL 範本

頁首

NuGet 提供者

認證

`metadata.repository`

NuGet 快取

提供者範例

GitHub 套件

Azure DevOps Artifacts

使用管線中的摘要

在本機使用摘要

ABI 哈希

zlib 的範例 ABI 哈希

其他資源

共用方式為

二進位快取組態

組態語法

提供者

AWS S3 提供者

Azure Blob 儲存體 提供者

快速入門

騰訊雲端物件儲存提供者

檔案提供者

Google Cloud Storage 提供者

快速入門

GitHub Actions 快取

快速入門

Azure Artifacts 中的通用套件

快速入門

HTTP 提供者

URL 範本

頁首

NuGet 提供者

認證

metadata.repository

NuGet 快取

提供者範例

GitHub 套件

Azure DevOps Artifacts

使用管線中的摘要

在本機使用摘要

ABI 哈希

zlib 的範例 ABI 哈希

其他資源

Azure Blob 儲存體提供者

`metadata.repository`