Configurazione della memorizzazione nella cache binaria

Sintassi di configurazione

La memorizzazione nella cache binaria viene configurata con la variabile VCPKG_BINARY_SOURCES di ambiente (impostata su <source>;<source>;...) e l'opzione --binarysource=<source>della riga di comando . Le opzioni vengono valutate prima dall'ambiente, quindi dalla riga di comando. La memorizzazione nella cache binaria può essere completamente disabilitata passando --binarysource=clear come ultima opzione della riga di comando.

Il <rw> parametro facoltativo per determinate origini controlla se verranno consultati per il download di file binari (read)(impostazione predefinita), se le compilazioni su richiesta verranno caricate in tale remoto (write) o entrambe (readwrite).

Provider

Provider AWS S3

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

Aggiungere un'origine AWS S3 usando l'interfaccia della riga di comando di AWS. <il prefisso> deve iniziare con s3:// e terminare in un oggetto /.

x-aws-config,no-sign-request

Passare --no-sign-request all'interfaccia della riga di comando di AWS.

provider Archiviazione BLOB di Azure

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

Aggiunge un provider di Archiviazione BLOB di Azure usando la convalida della firma di accesso condiviso. <baseuri> deve includere il percorso del contenitore.

Guida introduttiva

Prima di tutto, è necessario creare un account Archiviazione di Azure e un contenitore. Per istruzioni, vedere la documentazione di avvio rapido di Archiviazione di Azure.

Successivamente, sarà necessario creare una firma di accesso condiviso (SAS), che può essere eseguita dall'account di archiviazione in Impostazioni ->Firma di accesso condiviso. Questa firma di accesso condiviso richiederà:

• Servizi consentiti: BLOB
• Tipi di risorse consentiti: Oggetto
• Autorizzazioni consentite: lettura (se si usa ) o Lettura, Crea (se si usa readwrite o readwrite)

L'endpoint BLOB più il contenitore deve essere passato come <baseuri> e la firma di accesso condiviso generata senza il ? prefisso deve essere passata come <sas>.

Esempio:

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 tenterà di evitare di rivelare la firma di accesso condiviso durante le normali operazioni, tuttavia:

1. Verrà stampato in pieno se --debug viene passato
2. Verrà passato come parametro della riga di comando ai sottoprocessi, ad esempio curl.exe

Archiviazione BLOB di Azure include una funzionalità per rimuovere le voci della cache a cui non è stato eseguito l'accesso in un determinato numero di giorni che è possibile usare per gestire automaticamente le dimensioni della cache binaria. Per altre informazioni, vedere Gestione del ciclo di vita dei dati in Microsoft Docs oppure cercare Gestione dei dati -> Gestione del ciclo di vita nel portale di Azure per l'account di archiviazione.

Provider di archiviazione di oggetti cloud Tencent

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

Aggiunge un'origine COS. <prefix> deve iniziare con e terminare con cos:// /.

Provider di file

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

Archivia gli archivi compressi zip nel percorso in base all'ID di memorizzazione nella cache binaria.

Provider di Google Cloud Storage

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

Aggiunge un provider di Google Cloud Storage. <prefix> deve iniziare con e terminare con gs:// /.

Guida introduttiva

Prima di tutto, è necessario creare un account Google Cloud Platform e un bucket di archiviazione (Guida introduttiva GCS).

Nell'ambito di questa guida introduttiva è stato configurato lo gsutil strumento da riga di comando per l'autenticazione con Google Cloud. vcpkg userà questo strumento da riga di comando, quindi assicurarsi che si tratti del percorso di ricerca per i file eseguibili.

Esempio 1 (uso di un bucket senza un prefisso comune per gli oggetti):

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

Esempio 2 (usando un bucket e un prefisso per gli oggetti):

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

Le virgole (,) sono valide come parte di un prefisso dell'oggetto in GCS. Ricordarsi di eseguirne l'escape nella configurazione vcpkg, come illustrato nell'esempio precedente. GCS non dispone di cartelle (alcuni degli strumenti GCS simulano cartelle). Non è necessario creare o modificare il prefisso usato dalla cache vcpkg.

Cache di GitHub Actions

x-gha[,<rw>]

Aggiunge la cache di GitHub Actions come provider. Questo provider di memorizzazione nella cache binaria è valido solo nel contesto di un flusso di lavoro di GitHub Actions. Questo provider richiede che sia le variabili di ambiente che ACTIONS_RUNTIME_TOKEN le ACTIONS_CACHE_URL variabili di ambiente siano impostate. L'impostazione corretta di queste variabili di ambiente è illustrata nella sezione Avvio rapido seguente.

Guida introduttiva

Per consentire a vcpkg di usare la cache di GitHub Actions, è necessario l'URL della cache delle azioni e il token di runtime. A tale scopo, entrambi i valori devono essere esportati come variabili di ambiente in un passaggio del flusso di lavoro simile al seguente:

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

La specifica di questi valori come variabili di ambiente invece degli argomenti della riga di comando vcpkg è progettata perché il provider di memorizzazione nella cache binaria di GitHub Actions cache può essere usato solo da un flusso di lavoro di GitHub Actions.

Dopo aver esportato le variabili di ambiente, vcpkg può essere eseguito con il provider di memorizzazione nella cache binaria di GitHub Actions, come illustrato di seguito:

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

Pacchetti universali in Azure Artifacts

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

Aggiunge pacchetti universali in Azure Artifacts come provider.

Guida introduttiva

Prima di tutto, è necessario creare il feed pacchetti universali. Per istruzioni, vedere la guida introduttiva ai pacchetti universali.

Sarà quindi necessario installare ed eseguire l'autenticazione nell'interfaccia della riga di comando di Azure. Per istruzioni, vedere la guida all'autenticazione all'interfaccia della riga di comando di Azure. vcpkg userà questo strumento da riga di comando, quindi assicurarsi che si tratti del percorso di ricerca per i file eseguibili.

Esempio:

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

Specificare il project_name parametro per rendere vcpkg download e pubblicare pacchetti universali nel feed in un ambito di progetto.

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

Lasciare vuoto il project_name parametro per rendere vcpkg download e pubblicare pacchetti universali nel feed in un ambito dell'organizzazione.

Provider HTTP

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

Ogni operazione di memorizzazione nella cache binaria viene mappata a un verbo HTTP:

• Scaricare- GET
• Caricare- PUT
• Verifica esistenza - HEAD

Modello URL

Il modello usa parentesi graffe per l'espansione delle variabili. È possibile usare le variabili 'name', 'version', 'sha' e 'triplet'. Ad esempio:

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

Intestazione

L'autenticazione è supportata specificando un'intestazione di autorizzazione HTTP. Ad esempio:

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

Provider NuGet

Aggiungere un server NuGet con il parametro dell'interfaccia della -Source riga di comando di NuGet:

nuget,<uri>[,<rw>]

Usare un file di configurazione NuGet con il parametro dell'interfaccia della -Config riga di comando nuGet:

nugetconfig,<path>[,<rw>]

Configurare il timeout per le origini NuGet:

nugettimeout,<seconds>

I file di configurazione devono definire un defaultPushSource oggetto per supportare la scrittura di pacchetti nel feed.

Credenziali

Molti server NuGet richiedono credenziali aggiuntive per accedere. Il modo più flessibile per fornire le credenziali è tramite l'origine nugetconfig con un file personalizzato nuget.config . Per altre informazioni, vedere Utilizzo di pacchetti da feed autenticati.

Tuttavia, è comunque possibile eseguire l'autenticazione in molti server usando i provider di credenziali predefiniti di NuGet o personalizzando l'impostazione predefinita nuget.configdell'ambiente. La configurazione predefinita può essere estesa tramite chiamate client nuget, ad esempio:

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

e quindi passati a vcpkg tramite nuget,MyRemote,readwrite. È possibile ottenere un percorso alla copia precisa di NuGet usata da vcpkg eseguendo vcpkg fetch nuget, che invierà un report simile al seguente:

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

Gli utenti non Windows dovranno chiamare questa operazione tramite mono tramite mono /path/to/nuget.exe sources add ....

metadata.repository

I nuget provider di origine e nugetconfig rispettano determinate variabili di ambiente durante la generazione di pacchetti NuGet. Il metadata.repository campo di tutti i pacchetti verrà generato come:

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

or

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

se le variabili di ambiente appropriate sono definite e non vuote. Viene usato specificamente per associare i pacchetti in GitHub Packages al progetto di compilazione e non per associare le origini dei pacchetti originali.

NuGet Cache

La cache a livello di utente di NuGet non viene usata per impostazione predefinita. Per usarla per ogni origine basata su nuget, impostare la variabile di ambiente su true (senza distinzione tra maiuscole e minuscoleVCPKG_USE_NUGET_CACHE) o 1.

Esempi di provider

Se il sistema ci di scelta non è elencato, è possibile inviare una richiesta pull per aggiungerlo.

Pacchetti GitHub

Per usare vcpkg con GitHub Packages, è consigliabile usare il provider NuGet.

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

Se si usano manifesti, è possibile omettere il vcpkg package restore passaggio: verrà eseguito automaticamente come parte della compilazione.

Per altre informazioni, vedere la documentazione nuGet di GitHub Packages.

Artefatti di Azure DevOps

Per usare vcpkg con Azure DevOps Artifacts, è consigliabile usare il provider NuGet.

Verificare prima di tutto che Gli artefatti siano stati abilitati nell'account DevOps. Un amministratore può abilitare questa funzionalità tramite Impostazioni progetto ->Generale ->Panoramica ->Elementi di Azure DevOps Services>.

Creare quindi un feed per il progetto. L'URL del feed sarà un https:// collegamento che termina con /nuget/v3/index.json. Per altre informazioni, vedere la documentazione di Azure DevOps Artifacts.

Uso del feed da una 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

Se si usano agenti personalizzati con un sistema operativo non Windows, sarà necessario installare Mono per l'esecuzione nuget.exe (apt install mono-complete, brew install monoe così via).

Uso del feed in locale

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

Usare un token di accesso personale come password per la massima sicurezza. È possibile generare un token di accesso personale nelle impostazioni utente -> Token di accesso personale o https://dev.azure.com/<ORG>/_usersSettings/tokens .

ABI Hash

Per ogni compilazione, vcpkg calcola un hash ABI per determinare l'equivalenza. Se due compilazioni hanno lo stesso hash ABI, vcpkg le considererà identiche e riutilizza i file binari tra progetti e computer.

L'hash ABI prende in considerazione:

• Ogni file nella directory delle porte
• Contenuto e nome del file triplet
• File eseguibile del compilatore C++
• File eseguibile del compilatore C
• Set di funzionalità selezionate
• Hash ABI di ogni dipendenza
• Tutte le funzioni helper a cui fa portfile.cmake riferimento (euristica)
• Versione di CMake usata
• Contenuto di tutte le variabili di ambiente elencate in VCPKG_ENV_PASSTHROUGH
• Contenuto testuale del file toolchain (VCPKG_CHAINLOAD_TOOLCHAIN_FILE)
• Toolkit GRDK (solo quando la piattaforma Xbox è destinata alla piattaforma Xbox)

Nonostante questo elenco completo, è possibile sconfiggere la cache e introdurre non determinismo. Se sono presenti dettagli aggiuntivi da tenere traccia dell'ambiente, è possibile generare un file triplo con le informazioni aggiuntive in un commento. Tali informazioni aggiuntive verranno incluse nell'hash ABI e garantiranno un universo univoco di file binari.

I file denominati .DS_Store non vengono considerati per l'hash ABI.

Gli hash ABI calcolati vengono archiviati in ogni pacchetto e nella directory installata corrente in per /share/<port>/vcpkg_abi_info.txt l'ispezione.

Esempio di hash ABI di zlib

Abilitare l'output di debug per stampare l'hash ABI (Application Binary Interface) completo di un pacakge. Per 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

L'hash ABI per il pacchetto zlib viene costruito eseguendo l'hashing bb1c96759ac96102b4b18215db138daedd3eb16c2cd3302ae7bffab2b643eb87 di tutte le informazioni rilevanti possibili per distinguere i pacchetti binari.

La versione del compilatore fa parte dell'hash ABI e viene calcolata di seguito:

[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

I file, le informazioni sulla versione del compilatore e dello strumento pertinenti vengono sottoposto a hash per calcolare l'hash ABI finale:

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