二進位快取

vcpkg 公用登錄中的大部分埠都是從來源建置的。 透過從來源建置,vcpkg 可以使用相同的環境、建置工具、編譯程式旗標、連結器旗標,以及您在專案中用來建置相依性的其他組態,以確保最大的相容性。

啟用二進位快取時,從來源建置每個套件之後,vcpkg 會 建立二進位套件。 二進位套件會保存套件的組建輸出:二進位檔、建置系統整合檔案、使用檔、授權和其他檔案。 如果稍後的執行需要安裝快取的套件,vcpkg 會決定是否要還原快取的二進位套件,還是從來源觸發組建。

如此一來,二進位快取可減少從來源建置下列缺點的影響:

  • 重複的工作: 藉由減少需要從來源建置套件的次數。
  • 長時間建置時間: 還原二進位套件通常是一項非常快速的作業,需要幾秒鐘的時間才能完成。

在 CI 案例中,二進位快取特別有效,其中暫時容器或建置代理程式會強制 vcpkg 每次使用 clean-slate。 藉由使用雲端式二進位快取 (例如 GitHub PackagesAzure DevOps Artifacts ,您可以在執行之間保存二進位套件,以確保最大速度,因為只有在您對相依性或設定進行變更時才會重建。

雖然不建議作為二進位散發機制,但二進位快取可用來重複使用多個系統的組建輸出。 例如,開發人員可以使用 CI 在其本機電腦上執行的二進位套件。 如需重複使用和整合 vcpkg 產生的二進位檔的其他方法,請參閱 vcpkg export

提示

建議為每個持續整合管線或工作流程建立具有讀取和寫入許可權的二進位快取。 個別開發人員應該具有 CI 產生的二進位快取的唯讀存取權。

二進位快取可以裝載於各種環境中。 二進位快取中最基本的是本機計算機或網路檔案共用上的資料夾。 快取也可以儲存在任何 NuGet 摘要中(例如 GitHub Packages 或 Azure DevOps Artifacts)、Azure Blob 儲存體、Google Cloud 儲存體,以及其他許多服務。

如果您的 CI 提供者提供原生「快取」函式,建議您同時使用 vcpkg 二進位快取和原生方法,以取得最高效能的結果。

默認二進位快取

預設會啟用二進位快取,提供者位於下列第一個files有效位置:

  • Windows
  1. %VCPKG_DEFAULT_BINARY_CACHE%
  2. %LOCALAPPDATA%\vcpkg\archives
  3. %APPDATA%\vcpkg\archives
  • 非 Windows
  1. $VCPKG_DEFAULT_BINARY_CACHE
  2. $XDG_CACHE_HOME/vcpkg/archives
  3. $HOME/.cache/vcpkg/archives

透過提供 vcpkg help binarycaching減少的工具內說明。

二進位快取只涵蓋您建置的二進位檔。 若要快取來源檔案和預先建置的工具,請參閱 資產快取

組態語法

二進位快取已設定為 環境變數 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 儲存體 (GCS) 來源。
x-aws,<prefix>[,<rw>] 實驗性:將變更或移除而不發出警告
新增 AWS S3 來源。
x-aws-config,<parameter> 實驗性:將變更或移除而不發出警告
設定所有 AWS S3 提供者。
x-cos,<prefix>[,<rw>] 實驗性:將變更或移除而不發出警告
新增騰訊雲端物件 儲存體 來源。
x-gha,<rw>] 實驗性:將變更或移除而不發出警告
使用 GitHub Actions 快取作為來源。
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),此簽章可以從記憶體帳戶的 設定 ->Shared Access Signature完成。 此 SAS 需要:

  • 允許的服務: Blob
  • 允許的資源類型: 物件
  • 允許的權限:讀取(如果使用 read)或讀取、建立(如果使用 writereadwrite

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:

  1. 如果 --debug 通過,則會以完整列印
  2. 它會以命令行參數的形式傳遞至子進程,例如 curl.exe

Azure Blob 儲存體 包含一項功能,可移除在指定天數內尚未存取的快取專案,可用來自動管理二進位快取的大小。 如需詳細資訊,請參閱 Microsoft Docs 上的數據生命週期管理,或在 Azure 入口網站中尋找 記憶體帳戶的數據管理 ->生命週期管理

騰訊雲端物件 儲存體 提供者

注意

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

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

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

檔案提供者

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

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

Google Cloud 儲存體 提供者

注意

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

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

新增Google Cloud 儲存體提供者。 <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@v6
  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"

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

nugetnugetconfig 來源提供者在產生 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-vcpkgvcpkg 沒有路徑前置詞,可能會呼叫非預期的 vcpkg 實例。 如果您想要使用自己的 vcpkg 複本,下列兩個步驟可避免使用您自己的 vcpkg 複本時發生問題:

  1. 使用執行的 rm -rf "$VCPKG_INSTALLATION_ROOT" 對等專案 shell: 'bash'
  2. 一律呼叫 vcpkg ,並使用 bootstrap-vcpkg 路徑前置詞,例如 ./vcpkgvcpkg/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 帳戶上啟用成品。 管理員 istrator 可以透過 Project 設定 -General ->>Overview ->Azure DevOps Services>Artifacts 來啟用此功能。

接下來,為您的專案建立摘要。 您的摘要 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.exeapt install mono-completebrew 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) 作為最大安全性的密碼。 您可以在使用者 設定 ->Personal Access Tokenshttps://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

儘管這份廣泛的清單,但有可能擊敗快取並引入非決定性。 如果您有需要追蹤環境的其他詳細數據,您可以在批注中產生具有額外資訊的三重檔案。 該額外資訊將包含在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 工具鏈和編譯程式哈希。 如果您決定以不同的平臺為目標,這些哈希將會變更。