Konfiguration av binär cachelagring

Konfigurationssyntax

Binär cachelagring konfigureras med miljövariabeln VCPKG_BINARY_SOURCES (inställd på <source>;<source>;...) och kommandoradsalternativet --binarysource=<source>. Alternativen utvärderas först från miljön och sedan från kommandoraden. Binär cachelagring kan inaktiveras helt genom att skicka --binarysource=clear som det sista kommandoradsalternativet.

Form	Beskrivning
clear	Inaktivera alla tidigare källor (inklusive standard)
default[,<rw>]	Lägger till standard--filer provider
files,<absolute path>[,<rw>]	Lägger till en filbaserad plats
nuget,<uri>[,<rw>]	Lägger till en NuGet-baserad källa; motsvarar parametern -Source för NuGet CLI
nugetconfig,<path>[,<rw>]	Lägger till en NuGet-config-file-based source; motsvarar parametern -Config för NuGet CLI.
nugettimeout,<seconds>	Anger en tidsgräns för NuGet-nätverksåtgärder. motsvarar parametern -Timeout för NuGet CLI.
http,<url_template>[,<rw>[,<header>]]	Lägger till en anpassad http-baserad plats.
x-azblob,<baseuri>,<sas>[,<rw>]	Experimentell: ändras eller tas bort utan varning Lägger till en Azure Blob Storage-källa med en signatur för delad åtkomst
x-gcs,<prefix>[,<rw>]	Experimentell: ändras eller tas bort utan varning Lägger till en GCS-källa (Google Cloud Storage).
x-aws,<prefix>[,<rw>]	Experimentell: ändras eller tas bort utan varning Lägger till en AWS S3-källa.
x-aws-config,<parameter>	Experimentell: ändras eller tas bort utan varning Konfigurera alla AWS S3-leverantörer.
x-cos,<prefix>[,<rw>]	Experimentell: ändras eller tas bort utan varning Lägger till en Tencent Cloud Object Storage-källa.
x-gha,<rw>]	Experimentell: ändras eller tas bort utan varning Använd GitHub Actions-cachen som källa.
x-az-universal,<organization>,<project>,<feed>[,<rw>]	Experimentell: ändras eller tas bort utan varning Använd universella paket i Azure Artifacts som källa.
interactive	Aktiverar interaktiv hantering av autentiseringsuppgifter för NuGet- (för felsökning, kräver --debug på kommandoraden)

Den <rw> valfria parametern för vissa källor styr om de ska konsulteras för att ladda ned binärfiler (read)(standard), om versioner på begäran laddas upp till den fjärrplatsen (write), eller båda (readwrite).

Leverantörer

AWS S3-provider

Not

Det här avsnittet beskriver en experimentell funktion av vcpkg som kan ändras eller tas bort när som helst.

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

Lägg till en AWS S3-källa med hjälp av AWS CLI. <prefixet> bör börja med s3:// och sluta i en /.

x-aws-config,no-sign-request

Skicka --no-sign-request till AWS CLI.

Azure Blob Storage-provider

Not

Det här avsnittet beskriver en experimentell funktion av vcpkg som kan ändras eller tas bort när som helst.

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

Lägger till en Azure Blob Storage-provider med validering av signatur för delad åtkomst. <baseuri> ska innehålla containersökvägen.

Snabbstart

Först måste du skapa ett Azure Storage-konto och en container. Anvisningar finns i azure storage-snabbstartsdokumentationen.

Därefter måste du skapa en signatur för delad åtkomst (SAS), som kan göras från lagringskontot under Inställningar –>signatur för delad åtkomst. Denna SAS behöver:

• Tillåtna tjänster: Blob
• Tillåtna resurstyper: objekt
• Tillåtna behörigheter: Läs (om du använder read) eller Läs, Skapa (om du använder write eller readwrite)

Blobslutpunkten plus containern måste skickas som <baseuri> och den genererade SAS:en utan prefixet ? måste skickas som <sas>.

Exempel:

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 försöker undvika att avslöja SAS under normal drift, men:

1. Den skrivs ut i sin helhet om --debug skickas
2. Den skickas som en kommandoradsparameter till underprocesser, till exempel curl.exe

Azure Blob Storage innehåller en funktion för att ta bort cacheposter som inte har använts under ett visst antal dagar som kan användas för att automatiskt hantera storleken på din binära cache. Mer information finns i datalivscykelhantering i Microsoft Docs eller leta efter datahantering –>livscykelhantering i Azure-portalen för ditt lagringskonto.

Tencent Cloud Object Storage-provider

Not

Det här avsnittet beskriver en experimentell funktion av vcpkg som kan ändras eller tas bort när som helst.

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

Lägger till en COS-källa. <prefix> bör börja med cos:// och sluta med /.

Filprovider

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

Lagrar zip-komprimerade arkiv på sökvägen baserat på binär cachelagrings-ID.

Google Cloud Storage-provider

Not

Det här avsnittet beskriver en experimentell funktion av vcpkg som kan ändras eller tas bort när som helst.

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

Lägger till en Google Cloud Storage-provider. <prefix> bör börja med gs:// och sluta med /.

Snabbstart

Först måste du skapa ett Google Cloud Platform-konto samt en lagringshink (GCS Snabbstart].

Som en del av den här snabbstarten skulle du ha konfigurerat gsutil kommandoradsverktyget för att autentisera med Google Cloud. vcpkg använder det här kommandoradsverktyget, så se till att det finns i sökvägen för körbara filer.

Exempel 1 (med hjälp av en bucket utan ett vanligt prefix för objekten):

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

Exempel 2 (med hjälp av en bucket och ett prefix för objekten):

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

Kommatecken (,) är giltiga som en del av ett objektprefix i GCS. Kom ihåg att fly från dem i vcpkg-konfigurationen, som du ser i föregående exempel. GCS har inte mappar (vissa av GCS-verktygen simulerar mappar). Det är inte nödvändigt att skapa eller på annat sätt manipulera prefixet som används av vcpkg-cachen.

GitHub Actions-cache

Not

Det här avsnittet beskriver en experimentell funktion av vcpkg som kan ändras eller tas bort när som helst.

x-gha[,<rw>]

Lägger till GitHub Actions-cachen som leverantör. Den här providern för binär cachelagring är endast giltig i kontexten för ett GitHub Actions-arbetsflöde. Den här providern kräver att både ACTIONS_CACHE_URL och ACTIONS_RUNTIME_TOKEN miljövariabler anges. Inställningen av dessa miljövariabler beskrivs korrekt i följande snabbstartsavsnitt.

Snabbstart

För att vcpkg ska kunna använda GitHub Actions Cache behöver den url:en för actionscache och runtime-token. För att göra detta bör båda värdena exporteras som miljövariabler i ett arbetsflödessteg som liknar följande:

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

Att ange dessa värden som miljövariabler i stället för vcpkg-kommandoradsargument är avsiktligt eftersom providern för binär cachelagring i GitHub Actions Cache endast kan användas från ett GitHub Actions-arbetsflöde.

När miljövariablerna har exporterats kan vcpkg köras med providern för binär cachelagring i GitHub Actions så här:

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

Universella paket i Azure Artifacts

Not

Det här avsnittet beskriver en experimentell funktion av vcpkg som kan ändras eller tas bort när som helst.

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

Lägger till universella paket i Azure Artifacts som leverantör.

Snabbstart

Först måste du skapa Universal Packages-feed. Anvisningar finns i snabbstarten universella paket.

Därefter måste du installera och autentisera till Azure CLI. Anvisningar finns i autentisera till Azure CLI-guide. vcpkg använder det här kommandoradsverktyget, så se till att det finns i sökvägen för körbara filer.

Exempel:

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

Ange den project_name parametern för att hämta vcpkg och publicera universella paket i flödet i ett projektomfång.

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

Lämna parametern project_name tom för att hämta vcpkg och publicera universella paket i flödet i ett organisationsomfång.

HTTP-provider

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

Varje binär cachelagringsåtgärd mappas till ett HTTP-verb:

• Ladda ned – GET
• Ladda upp – PUT
• Kontrollera existens – HEAD

URL-mall

Mallen använder klammerparenteser för variabelexpansion. Du kan använda variablerna "name", "version", "sha" och "triplet". Till exempel:

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

Rubrik

Varning

Det här värdet kan visas på kommandoraden för externa processanrop, vilket kan få säkerhetskonsekvenser i din miljö.

Autentisering stöds genom att ange ett HTTP-auktoriseringshuvud. Till exempel:

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

NuGet-provider

Lägg till en NuGet-server med parametern -Source NuGet CLI:

nuget,<uri>[,<rw>]

Använd en NuGet-konfigurationsfil med parametern -Config NuGet CLI:

nugetconfig,<path>[,<rw>]

Konfigurera tidsgränsen för NuGet-källor:

nugettimeout,<seconds>

Konfigurationsfiler måste definiera en defaultPushSource för att kunna skriva paket tillbaka till feeden.

Autentiseringsuppgifter

Många NuGet-servrar kräver ytterligare autentiseringsuppgifter för åtkomst. Det mest flexibla sättet att ange autentiseringsuppgifter är via den nugetconfig källan med en anpassad nuget.config fil. Mer information finns i Använda paket från autentiserade feeds.

Det är dock fortfarande möjligt att autentisera mot många servrar med hjälp av NuGets inbyggda leverantörer av autentiseringsuppgifter eller genom att anpassa din miljös standard nuget.config. Standardkonfigurationen kan utökas via nuget-klientanrop, till exempel:

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

och sedan skickas till vcpkg via nuget,MyRemote,readwrite. Du kan hämta en sökväg till den exakta kopian av NuGet som används av vcpkg genom att köra vcpkg fetch nuget, som rapporterar ungefär så här:

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

Icke-Windows-användare måste anropa detta via mono via mono /path/to/nuget.exe sources add ....

metadata.repository

De nuget och nugetconfig källprovidrar respekterar vissa miljövariabler samtidigt som nuget-paket genereras. Fältet metadata.repository för alla paket genereras som:

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

eller

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

om lämpliga miljövariabler definieras och inte är tomma. Detta används specifikt för att associera paket i GitHub Packages med att skapa projekt och inte är avsedda att associeras med de ursprungliga paketkällorna.

NuGet Cache

NuGets användaromfattande cache används inte som standard. Om du vill använda den för varje nuget-baserad källa anger du miljövariabelnVCPKG_USE_NUGET_CACHE till true (skiftlägeskänslig) eller 1.

Providerexempel

Om ditt valfritt CI-system inte finns med i listan är du välkommen att skicka in en PR för att lägga till den!

GitHub-paket

Om du vill använda vcpkg med GitHub Packages rekommenderar vi att du använder NuGet-providern.

Not

2020-09-21: GitHubs värdbaserade agenter levereras med en äldre, förinstallerad kopia av vcpkg på sökvägen som inte stöder den senaste binära cachelagringen. Det innebär att direktanrop till bootstrap-vcpkg eller vcpkg utan sökvägsprefix kan anropa en oavsiktlig vcpkg-instans. Om du vill använda en egen kopia av vcpkg, följande två steg för att undvika problem om du vill använda din egen kopia av vcpkg:

1. Kör motsvarigheten till rm -rf "$VCPKG_INSTALLATION_ROOT" med hjälp av shell: 'bash'.
2. Anropa alltid vcpkg och bootstrap-vcpkg med ett sökvägsprefix, till exempel ./vcpkg, vcpkg/vcpkg, .\bootstrap-vcpkg.batosv.

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

Om du använder manifestkan du utelämna vcpkg package restore steg: det kommer att köras automatiskt som en del av bygget.

Mer information finns i nuget-dokumentationen för GitHub Packages.

Azure DevOps Artifacts

Om du vill använda vcpkg med Azure DevOps Artifacts rekommenderar vi att du använder NuGet-providern.

Kontrollera först att Artefakter har aktiverats på ditt DevOps-konto. En administratör kan aktivera detta via Projektinställningar –>Allmänt –>Översikt –>Azure DevOps Services>Artifacts.

Skapa sedan ett flöde för projektet. Din feed-URL blir en https:// länk som slutar med /nuget/v3/index.json. Mer information finns i dokumentationen Azure DevOps Artifacts.

Använda feeden från en pipeline

# 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

Om du använder anpassade agenter med ett icke-Windows-operativsystem måste du installera Mono för att köra nuget.exe (apt install mono-complete, brew install monoosv.).

Använda feeden lokalt

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

Använd en personlig åtkomsttoken (PAT) som lösenord för maximal säkerhet. Du kan generera en PAT i användarinställningar –>personliga åtkomsttoken eller https://dev.azure.com/<ORG>/_usersSettings/tokens.

ABI-hash

Not

Information om ABI-hashen tillhandahålls som en implementeringsanteckning och ändras utan föregående meddelande.

För varje version beräknar vcpkg en ABI Hash- för att fastställa likvärdighet. Om två versioner har samma ABI-hash kommer vcpkg att betrakta dem som identiska och återanvända binärfilerna mellan projekt och datorer.

ABI-hashen anser att:

• Varje fil i portkatalogen
• Trillingfilens innehåll och namn
• Körbar C++-kompilatorfil
• Körbar C-kompilatorfil
• Uppsättningen med funktioner valt
• ABI-hashen för varje beroende
• Alla hjälpfunktioner som refereras av portfile.cmake (heuristiska)
• Den version av CMake som används
• Den version av PowerShell som används (Windows)
• Innehållet i alla miljövariabler som anges i VCPKG_ENV_PASSTHROUGH
• Verktygskedjans textinnehåll (VCPKG_CHAINLOAD_TOOLCHAIN_FILE)
• GRDK-verktygslådan (endast när du riktar in dig på Xbox-plattformen)

Trots denna omfattande lista är det möjligt att besegra cachen och införa nondeterminism. Om du har ytterligare information som du behöver spåra för din miljö kan du generera en tripletfil med din ytterligare information i en kommentar. Den ytterligare informationen kommer att ingå i ABI-hashen och säkerställa ett unikt universum av binärfiler.

Filer med namnet .DS_Store beaktas inte för ABI-hashen.

De beräknade ABI-hashar lagras i varje paket och i den aktuella installerade katalogen vid /share/<port>/vcpkg_abi_info.txt för inspektion.

Exempel på ABI-hash för zlib

Aktivera felsöka utdata för att skriva ut den fullständiga ABI-hashen (Application Binary Interface) för en pacakge. För 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

ABI-hash-bb1c96759ac96102b4b18215db138daedd3eb16c2cd3302ae7bffab2b643eb87 för paket-zlib skapas genom hashning av all relevant information för att särskilja binära paket.

Versionen av kompilatorn är en del av ABI-hashen och beräknas nedan:

[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

Relevanta filer, kompilator- och verktygsversionsinformation hashas för att beräkna den slutliga ABI-hashen:

[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>

Not

Posten triplet_abi innehåller tre hashvärden: hashen för filinnehållet i x86-windows triplet, windows.cmake-verktygskedjan och kompilatorns hash. Dessa hashvärden skulle ändras om du bestämde dig för att rikta in dig på en annan plattform.