Configuración de almacenamiento en caché binario

Sintaxis de configuración

El almacenamiento en caché binario se configura con la variable VCPKG_BINARY_SOURCES de entorno (establecida <source>;<source>;...en ) y la opción --binarysource=<source>de línea de comandos . Las opciones se evalúan primero desde el entorno y, a continuación, desde la línea de comandos. El almacenamiento en caché binario se puede deshabilitar completamente pasando --binarysource=clear como la última opción de línea de comandos.

El <rw> parámetro opcional para determinados orígenes controla si se consultarán para descargar archivos binarios ()(readvalor predeterminado), si las compilaciones a petición se cargarán en ese remoto (write) o ambos (readwrite).

Proveedores

Proveedor de AWS S3

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

Agregue un origen de AWS S3 mediante la CLI de AWS. <el prefijo> debe comenzar por s3:// y terminar en ./

x-aws-config,no-sign-request

Pase --no-sign-request a la CLI de AWS.

Proveedor de Azure Blob Storage

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

Agrega un proveedor de Azure Blob Storage mediante la validación de firma de acceso compartido. <baseuri> debe incluir la ruta de acceso del contenedor.

Guía de inicio rápido

En primer lugar, debe crear una cuenta de Azure Storage, así como un contenedor. Consulte la documentación de inicio rápido de Azure Storage para obtener instrucciones.

A continuación, deberá crear una firma de acceso compartido (SAS), que se puede realizar desde la cuenta de almacenamiento en Configuración -> de acceso compartido. Esta SAS necesitará:

• Servicios permitidos: Blob
• Tipos de recursos permitidos: Object
• Permisos permitidos: leer (si usa read) o Leer, Crear (si usa write o readwrite)

El punto de conexión de blob más el contenedor debe pasarse como <baseuri> y la SAS generada sin el ? prefijo debe pasarse como <sas>.

Ejemplo:

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 intentará evitar revelar la SAS durante las operaciones normales, sin embargo:

1. Se imprimirá en su totalidad si --debug se pasa
2. Se pasará como parámetro de línea de comandos a subprocesos, como curl.exe

Azure Blob Storage incluye una característica para quitar las entradas de caché a las que no se ha accedido en un número determinado de días que se pueden usar para administrar automáticamente el tamaño de la caché binaria. Consulte Administración del ciclo de vida de los datos en Microsoft Docs para obtener más información o busque Administración de datos:> del ciclo de vida en Azure Portal para la cuenta de almacenamiento.

Azure Blob Storage con AzCopy

x-azcopy,<baseuri>[,<rw>]

Agrega un proveedor que usa la herramienta AzCopy para interactuar con un contenedor de Azure Blob Storage. La herramienta AzCopy admite métodos de autenticación no basados en SAS , como Microsoft Entra ID. Para usar la autenticación de tokens de SAS con AzCopy, use el x-azcopy-sas proveedor.

Se recomienda establecer la AZCOPY_AUTO_LOGIN_TYPE variable de entorno para su uso en escenarios no interactivos, por ejemplo, Integración continua. De lo contrario, debe cargar previamente las credenciales de AzCopy antes de ejecutar los comandos vcpkg mediante el azcopy login comando .

El <baseuri> parámetro debe incluir la ruta de acceso del contenedor, las direcciones URL predeterminadas de Azure Storage suelen seguir el formato: https://<account name>.blob.core.windows.net/<container name>.

Azure Blob Storage con AzCopy mediante un token de SAS

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

Agrega un proveedor que usa la herramienta AzCopy para interactuar con un contenedor de Azure Blob Storage. Este proveedor usa una autenticación de token de SAS que se anexa a cada solicitud de AzCopy.

El <baseuri> parámetro debe incluir la ruta de acceso del contenedor, las direcciones URL predeterminadas de Azure Storage suelen seguir el formato: https://<account name>.blob.core.windows.net/<container name>. El <sas> parámetro debe ser un token de SAS válido, lea la azblob guía de inicio rápido para obtener información sobre cómo generar un token de SAS válido.

Proveedor de almacenamiento de objetos en la nube de Tencent

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

Agrega un origen DE COS. <prefix> debe comenzar con cos:// y terminar con /.

Proveedor de archivos

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

Almacena archivos comprimidos zip en la ruta de acceso en función del identificador de almacenamiento en caché binario.

Proveedor de almacenamiento en la nube de Google

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

Agrega un proveedor de Google Cloud Storage. <prefix> debe comenzar con gs:// y terminar con /.

Guía de inicio rápido

En primer lugar, debe crear una cuenta de Google Cloud Platform, así como un cubo de almacenamiento (inicio rápido de GCS).

Como parte de este inicio rápido, habría configurado la gsutil herramienta de línea de comandos para autenticarse con Google Cloud. vcpkg usará esta herramienta de línea de comandos, por lo que debe asegurarse de que se encuentra en la ruta de búsqueda para los ejecutables.

Ejemplo 1 (mediante un cubo sin un prefijo común para los objetos):

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

Ejemplo 2 (mediante un depósito y un prefijo para los objetos):

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

Las comas (,) son válidas como parte de un prefijo de objeto en GCS. No olvide escaparlos en la configuración de vcpkg, como se muestra en el ejemplo anterior. GCS no tiene carpetas (algunas de las herramientas de GCS simulan carpetas). No es necesario crear o manipular de otro modo el prefijo usado por la memoria caché de vcpkg.

Caché de acciones de GitHub

Paquetes universales en Azure Artifacts

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

Agrega paquetes universales en Azure Artifacts como proveedor.

Guía de inicio rápido

En primer lugar, debe crear la fuente paquetes universales. Consulte la guía de inicio rápido paquetes universales para obtener instrucciones.

A continuación, deberá instalar y autenticarse en la CLI de Azure. Consulte la guía de autenticación en la CLI de Azure para obtener instrucciones. vcpkg usará esta herramienta de línea de comandos, por lo que debe asegurarse de que se encuentra en la ruta de búsqueda para los ejecutables.

Ejemplo:

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

Proporcione el project_name parámetro para que vcpkg descargue y publique paquetes universales en la fuente en un ámbito de proyecto.

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

Deje el project_name parámetro vacío para que vcpkg descargue y publique paquetes universales en la fuente en un ámbito de la organización.

Proveedor HTTP

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

Cada operación de almacenamiento en caché binaria se asigna a un verbo HTTP:

• Descargar- GET
• Subir- PUT
• Comprobar existencia: HEAD

Plantilla de URL

La plantilla usa llaves para la expansión de variables. Puede usar las variables 'name', 'version', 'sha' y 'triplet'. Por ejemplo:

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

Encabezado

La autenticación se admite especificando un encabezado de autorización HTTP. Por ejemplo:

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

Proveedor de NuGet

Agregue un servidor NuGet con el parámetro de la -Source CLI de NuGet:

nuget,<uri>[,<rw>]

Use un archivo de configuración de NuGet con el parámetro de la -Config CLI de NuGet:

nugetconfig,<path>[,<rw>]

Configure el tiempo de espera para los orígenes de NuGet:

nugettimeout,<seconds>

Los archivos de configuración deben definir para defaultPushSource admitir la escritura de paquetes en la fuente.

Credenciales

Muchos servidores NuGet requieren credenciales adicionales para acceder. La manera más flexible de proporcionar credenciales es a través del nugetconfig origen con un archivo personalizado nuget.config . Consulte Consumo de paquetes de fuentes autenticadas para obtener más información.

Sin embargo, todavía es posible autenticarse en muchos servidores mediante proveedores de credenciales integrados de NuGet o mediante la personalización del valor predeterminado nuget.configdel entorno. La configuración predeterminada se puede extender a través de llamadas de cliente nuget como:

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

y, a continuación, se pasa a vcpkg a través de nuget,MyRemote,readwrite. Puede obtener una ruta de acceso a la copia precisa de NuGet que usa vcpkg mediante la ejecución vcpkg fetch nugetde , que notificará algo parecido a:

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

Los usuarios que no son de Windows deberán llamar a esto a través de mono a través de mono /path/to/nuget.exe sources add ....

metadata.repository

Los nuget proveedores de origen y nugetconfig respetan determinadas variables de entorno al generar paquetes nuget. El metadata.repository campo de los paquetes se generará como:

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

o

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

si se definen las variables de entorno adecuadas y no están vacías. Esto se usa específicamente para asociar paquetes en Paquetes de GitHub con el proyecto de compilación y no está pensado para asociarse a los orígenes de paquetes originales.

Caché de NuGet

La caché en todo el usuario de NuGet no se usa de forma predeterminada. Para usarlo para cada origen basado en NuGet, establezca la VCPKG_USE_NUGET_CACHE de entorno en (sin distinción entre mayúsculas y minúsculas) o .true

Ejemplos de proveedor

Si el sistema de CI que prefiera no aparece en la lista, le damos la bienvenida a enviar una solicitud de incorporación de cambios para agregarlo.

Paquetes de GitHub

Para usar vcpkg con paquetes de GitHub, se recomienda usar el proveedor de 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 }}

Si usa manifiestos, puede omitir el vcpkg package restore paso: se ejecutará automáticamente como parte de la compilación.

Consulte la documentación de NuGet de paquetes de GitHub para obtener más información.

Artefactos de Azure DevOps

Para usar vcpkg con Azure DevOps Artifacts, se recomienda usar el proveedor de NuGet.

En primer lugar, asegúrese de que Artifacts se ha habilitado en la cuenta de DevOps. Un administrador puede habilitarlo a través de Configuración del proyecto ->General -> ->Artefactos de Azure DevOps Services.>

A continuación, cree una fuente para el proyecto. La dirección URL de la fuente será un https:// vínculo que termina con /nuget/v3/index.json. Para más información, consulte la documentación de Artefactos de Azure DevOps.

Uso de la fuente desde una canalización

# 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

Si usa agentes personalizados con un sistema operativo que no sea Windows, deberá instalar Mono para ejecutarse nuget.exe (apt install mono-complete, brew install mono, etc.).

Uso de la fuente localmente

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

Use un token de acceso personal (PAT) como contraseña para la máxima seguridad. Puede generar un PAT en Configuración de

ABI Hash

Para cada compilación, vcpkg calcula un hash abi para determinar la equivalencia. Si dos compilaciones tienen el mismo hash de ABI, vcpkg los considerará idénticos y reutilizará los archivos binarios entre proyectos y máquinas.

El hash de ABI tiene en cuenta lo siguiente:

• Todos los archivos del directorio de puertos
• El contenido y el nombre del archivo triplet
• El archivo ejecutable del compilador de C++
• El archivo ejecutable del compilador de C
• Conjunto de características seleccionada
• Hash abi de cada dependencia
• Todas las funciones auxiliares a las que hace portfile.cmake referencia (heurística)
• La versión de CMake usada
• La versión de PowerShell usada (Windows)
• El contenido de las variables de entorno enumeradas en VCPKG_ENV_PASSTHROUGH
• Contenido textual del archivo de cadena de herramientas (VCPKG_CHAINLOAD_TOOLCHAIN_FILE)
• El kit de herramientas de GRDK (solo cuando tiene como destino la plataforma Xbox)

A pesar de esta extensa lista, es posible derrotar la memoria caché e introducir no determinismo. Si tiene detalles adicionales que necesita para realizar el seguimiento de su entorno, puede generar un archivo triplet con su información adicional en un comentario. Esa información adicional se incluirá en el hash abi y garantizará un universo único de archivos binarios.

Los archivos denominados .DS_Store no se consideran para el hash abi.

Los hashes de ABI calculados se almacenan en cada paquete y en el directorio instalado actual en /share/<port>/vcpkg_abi_info.txt para su inspección.

Hash abi de ejemplo de zlib

Habilite la salida de depuración para imprimir el hash completo de la interfaz binaria de aplicaciones (ABI) de un ritmo. Para 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

El hash abi para el paquete zlib se construye mediante el hashbb1c96759ac96102b4b18215db138daedd3eb16c2cd3302ae7bffab2b643eb87 de toda la información pertinente posible para distinguir paquetes binarios.

La versión del compilador forma parte del hash abi y se calcula a continuación:

[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

Los archivos, el compilador y la información de la versión de la herramienta pertinentes se aplican hash para calcular el hash de ABI final:

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