Configuração de cache binário

Sintaxe de configuração

O cache binário é configurado com a variável de ambiente VCPKG_BINARY_SOURCES (definida como <source>;<source>;...) e a opção de linha de comando --binarysource=<source>. As opções são avaliadas primeiro a partir do ambiente e, em seguida, da linha de comando. O cache binário pode ser completamente desativado passando --binarysource=clear como a última opção de linha de comando.

O parâmetro opcional <rw> para determinadas fontes controla se elas serão consultadas para baixar binários (read(padrão), se as compilações sob demanda serão carregadas para esse remoto (write), ou ambas (readwrite).

Fornecedores

Provedor do AWS S3

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

Adicione uma origem do AWS S3 usando a AWS CLI. <prefixo> deve começar com s3:// e terminar em um /.

x-aws-config,no-sign-request

Passe --no-sign-request para a AWS CLI.

Provedor de Armazenamento de Blob do Azure

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

Adiciona um provedor de Armazenamento de Blob do Azure usando a validação de Assinatura de Acesso Compartilhado. <baseuri> deve incluir o caminho do contêiner.

Guia de início rápido

Primeiro, você precisa criar uma Conta de Armazenamento do Azure, bem como um contêiner. Consulte o de documentação de início rápido do Armazenamento do Azure para obter instruções.

Em seguida, você precisará criar um de Assinatura de Acesso Compartilhado (SAS) de, que pode ser feito a partir da conta de armazenamento em Configurações ->Assinatura de Acesso Compartilhado. Este SAS necessitará de:

• Serviços permitidos: Blob
• Tipos de recursos permitidos: Object
• Permissões permitidas: Ler (se estiver usando read) ou Ler, Criar (se estiver usando write ou readwrite)

O ponto de extremidade de blob mais o contêiner devem ser passados como o <baseuri> e o SAS gerado sem o prefixo ? deve ser passado como o <sas>.

Exemplo:

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 tentará evitar revelar o SAS durante operações normais, no entanto:

1. Será impresso na íntegra se --debug for aprovado
2. Ele será passado como um parâmetro de linha de comando para subprocessos, como curl.exe

O Armazenamento de Blobs do Azure inclui um recurso para remover entradas de cache que não foram acessadas em um determinado número de dias, que pode ser usado para gerenciar automaticamente o tamanho do cache binário. Consulte Gerenciamento do Ciclo de Vida de Dados no Microsoft Docs para obter mais informações ou procure de Gerenciamento de Dados -de Gerenciamento do Ciclo de Vida do> no Portal do Azure para sua conta de armazenamento.

Provedor de armazenamento de objetos em nuvem da Tencent

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

Adiciona uma fonte COS. <prefix> deve começar com cos:// e terminar com /.

Provedor de arquivos

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

Armazena arquivos compactados zip no caminho com base no ID de cache binário .

Fornecedor do Google Cloud Storage

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

Adiciona um provedor de armazenamento do Google Cloud. <prefix> deve começar com gs:// e terminar com /.

Guia de início rápido

Primeiro, você precisa criar uma conta do Google Cloud Platform, bem como um bucket de armazenamento (GCS Quick Start].

Como parte desse início rápido, você teria configurado a ferramenta de linha de comando gsutil para autenticação com o Google Cloud. vcpkg usará essa ferramenta de linha de comando, portanto, certifique-se de que está no seu caminho de pesquisa para executáveis.

Exemplo 1 (usando um bucket sem um prefixo comum para os objetos):

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

Exemplo 2 (usando um bucket e um prefixo para os 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

As vírgulas (,) são válidas como parte de um prefixo de objeto no GCS. Lembre-se de escapar deles na configuração vcpkg, como mostrado no exemplo anterior. O GCS não tem pastas (algumas das ferramentas GCS simulam pastas). Não é necessário criar ou manipular o prefixo usado pelo cache vcpkg.

Cache de ações do GitHub

x-gha[,<rw>]

Adiciona o cache de ações do GitHub como um provedor. Esse provedor de cache binário só é válido no contexto de um fluxo de trabalho de Ações do GitHub. Esse provedor requer que as variáveis de ambiente ACTIONS_CACHE_URL e ACTIONS_RUNTIME_TOKEN sejam definidas. A configuração correta dessas variáveis de ambiente é abordada na seção Guia de início rápido a seguir.

Guia de início rápido

Para que o vcpkg faça uso do Cache de Ações do GitHub, ele precisa da URL do Cache de Ações e do Token de Tempo de Execução. Para fazer isso, ambos os valores devem ser exportados como variáveis de ambiente em uma etapa de fluxo de trabalho semelhante à seguinte:

- 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 esses valores como variáveis de ambiente em vez de argumentos de linha de comando vcpkg é por design, pois o provedor de cache binário do Cache de Ações do GitHub só pode ser usado a partir de um fluxo de trabalho de Ações do GitHub.

Depois que as variáveis de ambiente tiverem sido exportadas, o vcpkg pode ser executado com o provedor de cache binário GitHub Actions da seguinte forma:

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

Pacotes universais em artefatos do Azure

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

Adiciona Pacotes Universais em Artefatos do Azure como um provedor.

Guia de início rápido

Primeiro, você precisa criar o feed de Pacotes Universais. Consulte o de início rápido Pacotes Universais para obter instruções.

Em seguida, você precisará instalar e autenticar na CLI do Azure. Consulte o guia autenticar na CLI do Azure para obter instruções. vcpkg usará essa ferramenta de linha de comando, portanto, certifique-se de que está no seu caminho de pesquisa para executáveis.

Exemplo:

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

Forneça o parâmetro project_name para fazer o download do vcpkg e publicar pacotes universais em seu feed no escopo de um projeto.

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

Deixe o parâmetro project_name vazio para fazer o download do vcpkg e publicar Pacotes Universais no seu feed no escopo da organização.

Provedor HTTP

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

Cada operação de cache binário é mapeada para um verbo HTTP:

• Baixar - GET
• Carregar - PUT
• Verificar existência - HEAD

Modelo de URL

O modelo usa colchetes encaracolados para expansão variável. Você pode usar as variáveis 'name', 'version', 'sha' e 'triplet'. Por exemplo:

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

Cabeçalho

A autenticação é suportada especificando um cabeçalho de autorização HTTP. Por exemplo:

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

Provedor NuGet

Adicione um servidor NuGet com o parâmetro -Source NuGet CLI:

nuget,<uri>[,<rw>]

Use um arquivo de configuração do NuGet com o parâmetro -Config NuGet CLI:

nugetconfig,<path>[,<rw>]

Configure o tempo limite para fontes NuGet:

nugettimeout,<seconds>

Os arquivos de configuração devem definir uma defaultPushSource para suportar a gravação de pacotes de volta para o feed.

Credenciais

Muitos servidores NuGet exigem credenciais adicionais para acessar. A maneira mais flexível de fornecer credenciais é através da fonte nugetconfig com um arquivo nuget.config personalizado. Consulte Consumindo pacotes de feeds autenticados para obter mais informações.

No entanto, ainda é possível autenticar em muitos servidores usando os provedores de credenciais internos do NuGet ou personalizando o nuget.configpadrão do seu ambiente. A configuração padrão pode ser estendida por meio de chamadas de cliente nuget, como:

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

e, em seguida, passou para vcpkg via nuget,MyRemote,readwrite. Você pode obter um caminho para a cópia precisa do NuGet usada pelo vcpkg executando vcpkg fetch nuget, que relatará algo como:

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

Os usuários que não são do Windows precisarão chamar isso através de mono via mono /path/to/nuget.exe sources add ....

metadata.repository

Os provedores de origem nuget e nugetconfig respeitam certas variáveis de ambiente ao gerar pacotes nuget. O campo metadata.repository de quaisquer pacotes será gerado como:

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

quer

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

se as variáveis de ambiente apropriadas estiverem definidas e não estiverem vazias. Isso é usado especificamente para associar pacotes em pacotes do GitHub com o construindo projeto e não se destina a associar com os códigos-fonte do pacote original.

NuGet Cache

O cache de todo o usuário do NuGet não é usado por padrão. Para usá-lo para cada fonte baseada em nuget, defina a variável de ambiente VCPKG_USE_NUGET_CACHE como true (sem distinção entre maiúsculas e minúsculas) ou 1.

Exemplos de fornecedores

Se o seu sistema de CI de escolha não estiver listado, você está convidado a enviar um PR para adicioná-lo!

Pacotes GitHub

Para usar vcpkg com pacotes GitHub, é recomendável usar o provedor 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 você estiver usando manifestos, você pode omitir a vcpkg package restore etapa: ele será executado automaticamente como parte de sua compilação.

Consulte a de documentação do NuGet dos pacotes GitHub para obter mais informações.

Artefatos do Azure DevOps

Para usar vcpkg com Artefatos de DevOps do Azure, é recomendável usar o provedor NuGet.

Primeiro, verifique se o Artifacts foi habilitado em sua conta de DevOps. Um Administrador pode habilitar isso por meio Configurações do Projeto -> Geral ->Visão Geral ->Azure DevOps Services>Artifacts.

Em seguida, crie um feed para seu projeto. O URL do feed será um link https:// que termina com /nuget/v3/index.json. Para obter mais informações, consulte o Azure DevOps Artifacts Documentation.

Usando o feed de um 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 você estiver usando agentes personalizados com um sistema operacional não-Windows, você precisará instalar o Mono para executar nuget.exe (apt install mono-complete, brew install mono, etc).

Usando o feed 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 um token de acesso pessoal (PAT) como senha para máxima segurança. Pode gerar uma PAT nas de Definições de Utilizador ->Tokens de Acesso Pessoal ou https://dev.azure.com/<ORG>/_usersSettings/tokens.

ABI Hash

Para cada compilação, vcpkg calcula um de hash ABI para determinar a equivalência. Se duas compilações tiverem o mesmo Hash ABI, o vcpkg as considerará idênticas e reutilizará os binários em projetos e máquinas.

O ABI Hash considera:

• Todos os arquivos no diretório de porta
• O conteúdo e o nome do arquivo triplete
• O arquivo executável do compilador C++
• O arquivo executável do compilador C
• O conjunto de recursos selecionado
• O Hash ABI de cada dependência
• Todas as funções auxiliares referenciadas por portfile.cmake (heurística)
• A versão do CMake usada
• A versão do PowerShell usada (Windows)
• O conteúdo de quaisquer variáveis de ambiente listadas em VCPKG_ENV_PASSTHROUGH
• Conteúdo textual do ficheiro toolchain (VCPKG_CHAINLOAD_TOOLCHAIN_FILE)
• O kit de ferramentas GRDK (somente quando direcionado para a plataforma Xbox)

Apesar desta extensa lista, é possível derrotar o cache e introduzir o não-determinismo. Se você tiver detalhes adicionais que precisa rastrear para seu ambiente, poderá gerar um arquivo triplete com suas informações adicionais em um comentário. Essas informações adicionais serão incluídas no ABI Hash e garantirão um universo único de binários.

Os arquivos nomeados .DS_Store não são considerados para o hash ABI.

Os Hashes ABI calculados são armazenados em cada pacote e no diretório atual instalado em /share/<port>/vcpkg_abi_info.txt para inspeção.

Exemplo ABI Hash de zlib

Habilite de saída de depuração para imprimir o hash completo da Interface Binária do Aplicativo (ABI) de um pacakge. 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

O bb1c96759ac96102b4b18215db138daedd3eb16c2cd3302ae7bffab2b643eb87 de hash ABI para o pacote zlib é construído por hash de todas as informações relevantes possíveis para distinguir pacotes binários.

A versão do seu compilador faz parte do hash ABI e é calculada abaixo:

[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

Arquivos relevantes, compilador e informações de versão da ferramenta são colocados em hash para calcular o hash 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>