Konfigurace binární mezipaměti

Syntaxe konfigurace

Binární ukládání do mezipaměti se konfiguruje s proměnnou VCPKG_BINARY_SOURCES prostředí (nastavenou na <source>;<source>;...) a možností --binarysource=<source>příkazového řádku . Možnosti se vyhodnocují jako první z prostředí a pak z příkazového řádku. Binární ukládání do mezipaměti je možné úplně zakázat předáním --binarysource=clear poslední možnosti příkazového řádku.

Formulář	Popis
clear	Zakázat všechny předchozí zdroje (včetně výchozího nastavení)
default[,<rw>]	Přidá výchozího zprostředkovatele souborů .
files,<absolute path>[,<rw>]	Přidá umístění založené na souborech.
nuget,<uri>[,<rw>]	Přidá zdroj založený na NuGetu; -Source ekvivalentní parametru rozhraní příkazového řádku NuGet
nugetconfig,<path>[,<rw>]	Přidá zdroj založený na nuGet-config-file; -Config ekvivalentní parametru rozhraní příkazového řádku NuGet.
nugettimeout,<seconds>	Určuje časový limit pro síťové operace NuGet; -Timeout ekvivalentní parametru rozhraní příkazového řádku NuGet.
http,<url_template>[,<rw>[,<header>]]	Přidá vlastní umístění založené na protokolu HTTP.
x-azblob,<baseuri>,<sas>[,<rw>]	Experimentální: změní se nebo odebere bez upozornění. Přidá zdroj služby Azure Blob Storage pomocí sdíleného přístupového podpisu.
x-gcs,<prefix>[,<rw>]	Experimentální: změní se nebo odebere bez upozornění. Přidá zdroj GCS (Google Cloud Storage).
x-aws,<prefix>[,<rw>]	Experimentální: změní se nebo odebere bez upozornění. Přidá zdroj AWS S3.
x-aws-config,<parameter>	Experimentální: změní se nebo odebere bez upozornění. Nakonfigurujte všechny poskytovatele AWS S3.
x-cos,<prefix>[,<rw>]	Experimentální: změní se nebo odebere bez upozornění. Přidá zdroj cloudového úložiště objektů Tencent.
x-gha,<rw>]	Experimentální: změní se nebo odebere bez upozornění. Jako zdroj použijte mezipaměť GitHub Actions.
x-az-universal,<organization>,<project>,<feed>[,<rw>]	Experimentální: změní se nebo odebere bez upozornění. Jako zdroj používejte univerzální balíčky v Azure Artifacts.
interactive	Povolí interaktivní správu přihlašovacích údajů pro NuGet (pro ladění, vyžaduje --debug se na příkazovém řádku).

Volitelný <rw> parametr pro určité zdroje určuje, jestli se budou poradit se stahováním binárních souborů (read)(výchozí), zda se sestavení na vyžádání nahrají do daného vzdáleného umístění (write) nebo obojí (readwrite).

Poskytovatelé

Poskytovatel AWS S3

Poznámka:

Tato část popisuje experimentální funkci vcpkg, která se může kdykoli změnit nebo odebrat.

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

Přidejte zdroj AWS S3 pomocí rozhraní příkazového řádku AWS. <předpona> by měla začínat s3:// a končit na ./

x-aws-config,no-sign-request

Předejte --no-sign-request rozhraní příkazového řádku AWS.

Poskytovatel služby Azure Blob Storage

Poznámka:

Tato část popisuje experimentální funkci vcpkg, která se může kdykoli změnit nebo odebrat.

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

Přidá zprostředkovatele služby Azure Blob Storage pomocí ověřování sdíleného přístupového podpisu. <baseuri> by měla obsahovat cestu ke kontejneru.

Rychlé zprovoznění

Nejprve musíte vytvořit účet úložiště Azure a také kontejner. Pokyny najdete v úvodní dokumentaci ke službě Azure Storage.

Dále budete muset vytvořit sdílený přístupový podpis (SAS), který můžete provést z účtu úložiště v části Nastavení ->Sdílený přístupový podpis. Tento SAS bude potřebovat:

• Povolené služby: Objekt blob
• Povolené typy prostředků: Objekt
• Povolená oprávnění: Čtení (pokud používáte read) nebo Číst, Vytvořit (pokud používáte write nebo readwrite)

Koncový bod objektu blob plus kontejner musí být předán jako <baseuri> sas a vygenerovaný SAS bez předpony ? musí být předán jako <sas>.

Příklad:

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 se pokusí vyhnout odhalení SAS během normálních operací, ale:

1. Pokud se předá, vytiskne se v plném rozsahu --debug .
2. Předá se jako parametr příkazového řádku podprocesům, jako je například curl.exe

Azure Blob Storage obsahuje funkci pro odebrání položek mezipaměti, ke kterým se v daném počtu dnů nepřistupuje, což se dá použít k automatické správě velikosti binární mezipaměti. Další informace najdete v tématu Správa životního cyklu dat na webu Microsoft Docs nebo vyhledejte správu dat –> správu životního cyklu na webu Azure Portal pro váš účet úložiště.

Poskytovatel cloudového úložiště objektů tencent

Poznámka:

Tato část popisuje experimentální funkci vcpkg, která se může kdykoli změnit nebo odebrat.

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

Přidá zdroj COS. <prefix>by měl začínat cos:// a končit ./

Zprostředkovatel souborů

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

Ukládá komprimované archivy zip na cestě na základě ID binární mezipaměti.

Poskytovatel cloudového úložiště Google

Poznámka:

Tato část popisuje experimentální funkci vcpkg, která se může kdykoli změnit nebo odebrat.

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

Přidá poskytovatele cloudového úložiště Google. <prefix>by měl začínat gs:// a končit ./

Rychlé zprovoznění

Nejprve musíte vytvořit účet Google Cloud Platform a kontejner úložiště (Rychlý start GCS).

V rámci tohoto rychlého startu jste nakonfigurovali gsutil nástroj příkazového řádku pro ověření pomocí Google Cloudu. Nástroj příkazového řádku použije nástroj vcpkg, proto se ujistěte, že je ve vaší cestě hledání spustitelných souborů.

Příklad 1 (použití kbelíku bez společné předpony pro objekty):

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

Příklad 2 (použití kontejneru a předpony pro objekty):

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

Čárky (,) jsou platné jako součást předpony objektu v GCS. Nezapomeňte je utéct v konfiguraci vcpkg, jak je znázorněno v předchozím příkladu. GCS nemá složky (některé nástroje GCS simulují složky). Předponu používanou mezipamětí vcpkg není nutné vytvářet ani jinak manipulovat.

Mezipaměť GitHub Actions

Poznámka:

Tato část popisuje experimentální funkci vcpkg, která se může kdykoli změnit nebo odebrat.

x-gha[,<rw>]

Přidá mezipaměť GitHub Actions jako poskytovatele. Tento zprostředkovatel binární mezipaměti je platný pouze v kontextu pracovního postupu GitHub Actions. Tento zprostředkovatel vyžaduje, aby byly nastaveny obě ACTIONS_CACHE_URL proměnné prostředí i ACTIONS_RUNTIME_TOKEN proměnné prostředí. Správné nastavení těchto proměnných prostředí najdete v následující části Rychlý start.

Rychlé zprovoznění

Aby nástroj vcpkg mohl využívat mezipaměť GitHub Actions Cache, potřebuje adresu URL mezipaměti Actions a token modulu runtime. Chcete-li to provést, měly by být obě hodnoty exportovány jako proměnné prostředí v kroku pracovního postupu podobnému následujícímu:

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

Zadání těchto hodnot jako proměnných prostředí místo argumentů příkazového řádku vcpkg je návrhem, protože zprostředkovatel binární mezipaměti GitHub Actions Cache lze použít pouze z pracovního postupu GitHub Actions.

Po exportu proměnných prostředí je možné vcpkg spustit s poskytovatelem binární mezipaměti GitHub Actions, například takto:

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

Univerzální balíčky v Azure Artifacts

Poznámka:

Tato část popisuje experimentální funkci vcpkg, která se může kdykoli změnit nebo odebrat.

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

Přidá univerzální balíčky v Azure Artifacts jako poskytovatele.

Rychlé zprovoznění

Nejprve je potřeba vytvořit informační kanál Universal Packages. Pokyny najdete v rychlém startu Pro univerzální balíčky.

V dalším kroku budete muset nainstalovat a ověřit azure CLI. Pokyny najdete v průvodci ověřováním v Azure CLI. Nástroj příkazového řádku použije nástroj vcpkg, proto se ujistěte, že je ve vaší cestě hledání spustitelných souborů.

Příklad:

x-az-universal,organization_url,project_name,feed_name,readwrite

project_name Zadejte parametr pro stažení a publikování univerzálních balíčků vcpkg do informačního kanálu v oboru projektu.

x-az-universal,organization_url,,feed_name,readwrite

project_name Nechte parametr prázdný, aby se vcpkg stáhly a publikovaly univerzální balíčky do informačního kanálu v oboru organizace.

Zprostředkovatel HTTP

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

Každá operace binární mezipaměti se mapuje na příkaz HTTP:

• Stáhnout- GET
• Upload- PUT
• Kontrola existence – HEAD

Šablona URL

Šablona používá složené závorky pro rozšíření proměnných. Můžete použít proměnné name, version, sha a triplet. Příklad:

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

Hlavička

Upozorňující

Tato hodnota se může zobrazit na příkazovém řádku volání externího procesu, což může mít vliv na zabezpečení ve vašem prostředí.

Ověřování se podporuje zadáním autorizační hlavičky HTTP. Příklad:

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

Zprostředkovatel NuGet

Přidejte server NuGet s parametrem rozhraní příkazového -Source řádku NuGet:

nuget,<uri>[,<rw>]

Použijte konfigurační soubor NuGet s parametrem Rozhraní příkazového -Config řádku NuGet:

nugetconfig,<path>[,<rw>]

Konfigurace časového limitu pro zdroje NuGet:

nugettimeout,<seconds>

Konfigurační soubory musí definovat defaultPushSource podporu zápisu balíčků zpět do informačního kanálu.

Přihlašovací údaje

Mnoho serverů NuGet vyžaduje pro přístup další přihlašovací údaje. Nejflexibilnější způsob, jak zadat přihlašovací údaje, je prostřednictvím nugetconfig zdroje s vlastním nuget.config souborem. Další informace najdete v tématu Využívání balíčků z ověřených informačních kanálů.

Přesto je ale možné provést ověření na mnoha serverech pomocí integrovaných zprostředkovatelů přihlašovacích údajů NuGet nebo přizpůsobením výchozího nastavení nuget.configvašeho prostředí . Výchozí konfiguraci je možné rozšířit prostřednictvím volání klienta NuGet, například:

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

a pak předán do vcpkg přes nuget,MyRemote,readwrite. Můžete získat cestu k přesné kopii NuGetu, kterou používá vcpkg spuštěním vcpkg fetch nugetpříkazu , který bude hlásit něco jako:

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

Uživatelé, kteří nejsou windows, budou muset volat prostřednictvím mono prostřednictvím .mono /path/to/nuget.exe sources add ...

metadata.repository

Poskytovatelé nuget a nugetconfig poskytovatelé zdrojů respektují určité proměnné prostředí při generování balíčků NuGet. Pole metadata.repository všech balíčků se vygeneruje takto:

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

nebo

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

pokud jsou definovány příslušné proměnné prostředí a nejsou prázdné. Toto se konkrétně používá k přidružení balíčků v GitHub Packages k projektu sestavení , a ne k přidružení k původním zdrojům balíčků.

Mezipaměť NuGet

Mezipaměť NuGet pro uživatele se ve výchozím nastavení nepoužívá. Pokud ji chcete použít pro každý zdroj založený na nugetu, nastavte proměnnouVCPKG_USE_NUGET_CACHE prostředí na true (nerozlišující malá a velká písmena) nebo 1.

Příklady poskytovatelů

Pokud váš zvolený systém CI není uvedený, můžete odeslat žádost o přijetí změn a přidat ji.

GitHub Packages

Pokud chcete používat vcpkg se službami GitHub Packages, doporučujeme použít poskytovatele NuGet.

Poznámka:

2020-09-21: Hostovaní agenti GitHubu mají starší předinstalovanou kopii vcpkg na cestě, která nepodporuje nejnovější binární ukládání do mezipaměti. To znamená, že přímé volání na bootstrap-vcpkg předponu cesty nebo vcpkg bez této předpony mohou volat nezamýšlené instance vcpkg. Pokud chcete použít vlastní kopii vcpkg, následující dva kroky, abyste se vyhnuli problémům, pokud chcete použít vlastní kopii vcpkg:

1. Spusťte ekvivalent rm -rf "$VCPKG_INSTALLATION_ROOT" použití shell: 'bash'.
2. Vždy volat vcpkg a bootstrap-vcpkg s předponou cesty, například ./vcpkg, vcpkg/vcpkg, .\bootstrap-vcpkg.batatd.

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

Pokud používáte manifesty, můžete tento krok vynechat vcpkg package restore : tento krok se spustí automaticky jako součást sestavení.

Další informace najdete v dokumentaci NuGet služby GitHub Packages.

Artefakty Azure DevOps

Pokud chcete použít vcpkg s Azure DevOps Artifacts, doporučujeme použít poskytovatele NuGet.

Nejprve se ujistěte, že je pro váš účet DevOps povolená služba Artifacts. Správce to může povolit prostřednictvím nastavení projektu ->Obecné ->Overview ->Azure DevOps Services>Artifacts.

Dále vytvořte informační kanál pro váš projekt. Adresa URL vašeho informačního https:// kanálu bude odkaz končící na /nuget/v3/index.json. Další informace najdete v dokumentaci k artefaktům Azure DevOps.

Použití informačního kanálu z kanálu

# 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

Pokud používáte vlastní agenty s operačním systémem jiného systému než Windows, budete muset nainstalovat Mono ke spuštění nuget.exe (apt install mono-completeatd brew install mono.).

Místní používání informačního kanálu

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

Jako heslo pro maximální zabezpečení použijte token PAT (Personal Access Token). Tokeny PAT můžete vygenerovat v uživatelských nastaveních -> osobní přístupové tokeny nebo https://dev.azure.com/<ORG>/_usersSettings/tokens.

ABI Hash

Poznámka:

Informace o hodnotě hash ABI jsou poskytovány jako poznámka k implementaci a změní se bez předchozího upozornění.

Pro každé sestavení vcpkg vypočítá hodnotu hash ABI, která určí ekvivalenci. Pokud mají dvě sestavení stejnou hodnotu hash ABI, vcpkg je bude považovat za identické a znovu použije binární soubory napříč projekty a počítači.

Hodnota hash ABI bere v úvahu:

• Každý soubor v adresáři portů
• Obsah a název trojitého souboru
• Spustitelný soubor kompilátoru C++
• Spustitelný soubor kompilátoru jazyka C
• Vybraná sada funkcí
• Hodnota hash ABI každé závislosti
• Všechny pomocné funkce, na které portfile.cmake odkazuje (heuristické)
• Použitá verze CMake
• Obsah všech proměnných prostředí uvedených v VCPKG_ENV_PASSTHROUGH
• Textový obsah souboru sady nástrojů (VCPKG_CHAINLOAD_TOOLCHAIN_FILE)
• Sada nástrojů GRDK (pouze při cílení na platformu Xbox)

Navzdory tomuto rozsáhlému seznamu je možné porazit mezipaměť a zavést nedeterminismus. Pokud máte další podrobnosti, které potřebujete sledovat pro své prostředí, můžete vygenerovat trojitý soubor s dalšími informacemi v komentáři. Další informace budou zahrnuty do hodnoty hash ABI a zajistí jedinečný vesmír binárních souborů.

Pojmenované .DS_Store soubory se nepovažují za hodnotu hash ABI.

Počítané hodnoty hash ABI jsou uloženy v každém balíčku a v aktuálním nainstalovaném adresáři pro /share/<port>/vcpkg_abi_info.txt kontrolu.

Příklad hodnoty hash ABI zlib

Povolením výstupu ladění vytiskněte úplnou hodnotu hash ABI (Application Binary Interface) pacakge. Pro 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

Hodnota hash bb1c96759ac96102b4b18215db138daedd3eb16c2cd3302ae7bffab2b643eb87 ABI pro balíček zlib je vytvořena hodnotou hash všech možných relevantních informací k rozlišení binárních balíčků.

Verze kompilátoru je součástí hodnoty hash ABI a vypočítá se níže:

[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

Relevantní soubory, informace o verzi kompilátoru a nástroje se zatřiďují za účelem výpočtu konečné hodnoty hash 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>

Poznámka:

Položka triplet_abi obsahuje tři hodnoty hash: hodnotu hash obsahu x86-windows souboru tripletu, windows.cmake sadu nástrojů a hodnotu hash kompilátoru. Tyto hodnoty hash by se změnily, pokud jste se rozhodli cílit na jinou platformu.