二進位快取組態
二進位快取已設定為 環境變數 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>
特定來源的選擇性參數會控制是否要查閱下載二進位檔 ()(預設值)、隨選組建是否會上傳至該遠端或read
write
兩者(readwrite
)。
注意
本節涵蓋 vcpkg 的實驗功能,隨時可能會變更或移除。
x-aws,<prefix>[,<rw>]
使用 AWS CLI 新增 AWS S3 來源。 <前置詞> 應該以 開頭 s3://
,並以 結尾 /
。
x-aws-config,no-sign-request
傳遞 --no-sign-request
至 AWS CLI。
注意
本節涵蓋 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 壓縮封存儲存在路徑上。
注意
本節涵蓋 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 快取所使用的前置詞。
注意
本節涵蓋 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"
注意
本節涵蓋 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,<url_template>[,<rw>[,<header>]]
每個二進位快取作業都會對應至 HTTP 動詞命令:
- 下載-
GET
- 上傳-
PUT
- 檢查是否存在 -
HEAD
此範本會使用大括弧進行變數展開。 您可以使用變數 '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 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 ...
透過 單聲道呼叫此帳戶。
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 為基礎的來源使用,請將 環境變數VCPKG_USE_NUGET_CACHE
設定為 true
(不區分大小寫) 或 1
。
如果未列出您選擇的 CI 系統,歡迎提交 PR 以新增它!
若要搭配 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 使用 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 哈希的資訊會以實作注意事項的形式提供,而且不會通知變更。
針對每個組建,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
以供檢查。
啟用 偵錯輸出 ,以列印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
工具鏈和編譯程式哈希。 如果您決定以不同的平臺為目標,這些哈希將會變更。