Configuración de almacenamiento en caché binario

Article
10/30/2024

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.

Form	Descripción
`clear`	Deshabilitar todos los orígenes anteriores (incluido el valor predeterminado)
`default[,<rw>]`	Agrega el proveedor de archivos predeterminado
`files,<absolute path>[,<rw>]`	Agrega una ubicación basada en archivos
`nuget,<uri>[,<rw>]`	Agrega un origen basado en NuGet; equivalente al `-Source` parámetro de la CLI de NuGet
`nugetconfig,<path>[,<rw>]`	Agrega un origen basado en nuGet-config-file; equivalente al `-Config` parámetro de la CLI de NuGet.
`nugettimeout,<seconds>`	Especifica un tiempo de espera para las operaciones de red NuGet; equivalente al `-Timeout` parámetro de la CLI de NuGet.
`http,<url_template>[,<rw>[,<header>]]`	Agrega una ubicación personalizada basada en HTTP.
`x-azblob,<baseuri>,<sas>[,<rw>]`	Experimental: cambiará o se quitará sin advertencia Agrega un origen de Azure Blob Storage mediante una firma de acceso compartido
`x-gcs,<prefix>[,<rw>]`	Experimental: cambiará o se quitará sin advertencia Agrega un origen de Google Cloud Storage (GCS).
`x-aws,<prefix>[,<rw>]`	Experimental: cambiará o se quitará sin advertencia Agrega un origen de AWS S3.
`x-aws-config,<parameter>`	Experimental: cambiará o se quitará sin advertencia Configure todos los proveedores de AWS S3.
`x-cos,<prefix>[,<rw>]`	Experimental: cambiará o se quitará sin advertencia Agrega un origen de Almacenamiento de objetos en la nube tencent.
`x-gha,<rw>]`	Experimental: cambiará o se quitará sin advertencia Use la caché de Acciones de GitHub como origen.
`x-az-universal,<organization>,<project>,<feed>[,<rw>]`	Experimental: cambiará o se quitará sin advertencia Use paquetes universales en Azure Artifacts como origen.
`interactive`	Habilita la administración interactiva de credenciales para NuGet (para la depuración; requiere `--debug` en la 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

Nota:

En esta sección se describe una característica experimental de vcpkg que puede cambiar o quitarse en cualquier momento.

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

Nota:

En esta sección se describe una característica experimental de vcpkg que puede cambiar o quitarse en cualquier momento.

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.

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 ->Firma 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:

Se imprimirá en su totalidad si --debug se pasa
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:> administración del ciclo de vida en Azure Portal para la cuenta de almacenamiento.

Proveedor de almacenamiento de objetos en la nube de Tencent

Nota:

En esta sección se describe una característica experimental de vcpkg que puede cambiar o quitarse en cualquier momento.

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

Nota:

En esta sección se describe una característica experimental de vcpkg que puede cambiar o quitarse en cualquier momento.

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

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

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

Nota:

En esta sección se describe una característica experimental de vcpkg que puede cambiar o quitarse en cualquier momento.

x-gha[,<rw>]

Agrega la memoria caché de Acciones de GitHub como proveedor. Este proveedor de almacenamiento en caché binario solo es válido en el contexto de un flujo de trabajo de Acciones de GitHub. Este proveedor requiere que se establezcan las ACTIONS_CACHE_URL variables de entorno y ACTIONS_RUNTIME_TOKEN . La configuración correcta de estas variables de entorno se describe en la siguiente sección inicio rápido.

Inicio rápido

Para que vcpkg use la caché de acciones de GitHub, necesita la dirección URL de caché de acciones de Actions y el token de tiempo de ejecución. Para ello, ambos valores deben exportarse como variables de entorno en un paso de flujo de trabajo similar al siguiente:

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

Especificar estos valores como variables de entorno en lugar de argumentos de línea de comandos vcpkg es por diseño, ya que el proveedor de almacenamiento en caché binario de Caché de acciones de GitHub solo se puede usar desde un flujo de trabajo de Acciones de GitHub.

Una vez exportadas las variables de entorno, vcpkg se puede ejecutar con el proveedor de almacenamiento en caché binario de Acciones de GitHub como este:

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

Paquetes universales en Azure Artifacts

Nota:

En esta sección se describe una característica experimental de vcpkg que puede cambiar o quitarse en cualquier momento.

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

Agrega paquetes universales en Azure Artifacts como proveedor.

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}

Advertencia

Este valor puede aparecer en la línea de comandos de las llamadas a procesos externos, lo que puede tener implicaciones de seguridad en su entorno.

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}"/>

    <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 variable trueVCPKG_USE_NUGET_CACHE de entorno en (sin distinción entre mayúsculas y minúsculas) o .1

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.

GitHub Packages

Para usar vcpkg con paquetes de GitHub, se recomienda usar el proveedor de NuGet.

Nota:

2020-09-21: los agentes hospedados de GitHub incluyen una copia anterior y preinstalada de vcpkg en la ruta de acceso que no admite el almacenamiento en caché binario más reciente. Esto significa que las llamadas directas a bootstrap-vcpkg o vcpkg sin un prefijo de ruta de acceso pueden llamar a una instancia de vcpkg no deseada. Si desea usar su propia copia de vcpkg, los dos pasos siguientes para evitar problemas si desea usar su propia copia de vcpkg:

Ejecute el equivalente de rm -rf "$VCPKG_INSTALLATION_ROOT" usar shell: 'bash'.
Llame vcpkg siempre a y bootstrap-vcpkg con un prefijo de ruta de acceso, como ./vcpkg, vcpkg/vcpkg, .\bootstrap-vcpkg.batetc.

# 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 ->Información 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 usuario ->Tokens de acceso personal o https://dev.azure.com/<ORG>/_usersSettings/tokens.

ABI Hash

Nota:

La información sobre el hash de ABI se proporciona como una nota de implementación y cambiará sin previo aviso.

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
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 hash bb1c96759ac96102b4b18215db138daedd3eb16c2cd3302ae7bffab2b643eb87 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>

Nota:

La triplet_abi entrada contiene tres hashes: el hash del contenido del archivo del x86-windows triplet, la windows.cmake cadena de herramientas y el hash del compilador. Estos hash cambiarían si decide establecer como destino una plataforma diferente.

Comparteix a través de

Configuración de almacenamiento en caché binario

Sintaxis de configuración

Proveedores

Proveedor de AWS S3

Proveedor de Azure Blob Storage

Inicio rápido

Proveedor de almacenamiento de objetos en la nube de Tencent

Proveedor de archivos

Proveedor de almacenamiento en la nube de Google

Inicio rápido

Caché de acciones de GitHub

Inicio rápido

Paquetes universales en Azure Artifacts

Inicio rápido

Proveedor HTTP

Plantilla de URL

Encabezado

Proveedor de NuGet

Credenciales

`metadata.repository`

Caché de NuGet

Ejemplos de proveedor

GitHub Packages

Artefactos de Azure DevOps

Uso de la fuente desde una canalización

Uso de la fuente localmente

ABI Hash

Hash abi de ejemplo de zlib

Recursos addicionals