Compartilhar via

Configuração de cache binário

  • Artigo

Sintaxe de configuração

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

Formulário Descrição
clear Desative todas as fontes anteriores (incluindo o padrão)
default[,<rw>] Adiciona o provedor de arquivos padrão
files,<absolute path>[,<rw>] Adiciona um local baseado em arquivo
nuget,<uri>[,<rw>] Adiciona uma fonte baseada em NuGet; equivalente ao -Source parâmetro da CLI do NuGet
nugetconfig,<path>[,<rw>] Adiciona uma fonte baseada em arquivo de configuração do NuGet; equivalente ao -Config parâmetro da CLI do NuGet.
nugettimeout,<seconds> Especifica um tempo limite para operações de rede NuGet; equivalente ao -Timeout parâmetro da CLI do NuGet.
http,<url_template>[,<rw>[,<header>]] Adiciona um local personalizado baseado em http.
x-azblob,<baseuri>,<sas>[,<rw>] Experimental: mudará ou será removido sem aviso prévio
Adiciona uma fonte de Armazenamento de Blobs do Azure usando uma Assinatura de Acesso Compartilhado
x-gcs,<prefix>[,<rw>] Experimental: mudará ou será removido sem aviso prévio
Adiciona uma fonte do Google Cloud Storage (GCS).
x-aws,<prefix>[,<rw>] Experimental: mudará ou será removido sem aviso prévio
Adiciona uma fonte do AWS S3.
x-aws-config,<parameter> Experimental: mudará ou será removido sem aviso prévio
Configure todos os provedores do AWS S3.
x-cos,<prefix>[,<rw>] Experimental: mudará ou será removido sem aviso prévio
Adiciona uma fonte Tencent Cloud Object Storage.
x-gha,<rw>] Experimental: mudará ou será removido sem aviso prévio
Use o cache do GitHub Actions como origem.
x-az-universal,<organization>,<project>,<feed>[,<rw>] Experimental: mudará ou será removido sem aviso prévio
Use Pacotes Universais no Azure Artifacts como origem.
interactive Habilita o gerenciamento de credenciais interativo para NuGet (para depuração; requer --debug na linha de comando)

O <rw> parâmetro opcional 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 ambos (readwrite).

Provedores

Provedor do AWS S3

Observação

Esta seção cobre um recurso experimental do vcpkg que pode ser alterado ou removido a qualquer momento.

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

Adicione uma fonte do AWS S3 usando a AWS CLI. <> 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 Blobs do Azure

Observação

Esta seção cobre um recurso experimental do vcpkg que pode ser alterado ou removido a qualquer momento.

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

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

Início rápido

Primeiro, você precisa criar uma conta de armazenamento do Azure, bem como um contêiner. Consulte a Documentação de Início Rápido do Armazenamento do Azure para obter instruções.

Em seguida, você precisará criar uma SAS (Assinatura de Acesso Compartilhado ), o que pode ser feito na conta de armazenamento em Configurações –> Assinatura de Acesso Compartilhado. Essa SAS precisará de:

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

O ponto de extremidade do blob mais o contêiner deve ser passado como o e a <baseuri> SAS gerada sem o prefixo ? deve ser passada 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

No entanto, o vcpkg tentará evitar revelar a SAS durante as operações normais:

  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 Gerenciamento de dados –> Gerenciamento do ciclo de vida no Portal do Azure para sua conta de armazenamento.

Provedor de armazenamento de objetos em nuvem Tencent

Observação

Esta seção cobre um recurso experimental do vcpkg que pode ser alterado ou removido a qualquer momento.

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 em zip no caminho com base na ID de cache binário.

Provedor do Google Cloud Storage

Observação

Esta seção cobre um recurso experimental do vcpkg que pode ser alterado ou removido a qualquer momento.

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

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

Início rápido

Primeiro, você precisa criar uma conta do Google Cloud Platform e um bucket de armazenamento (início rápido do GCS).

Como parte deste início rápido, você teria configurado a ferramenta de linha de comando para autenticar com o gsutil Google Cloud. O vcpkg usará essa ferramenta de linha de comando, portanto, certifique-se de que ela esteja no caminho de pesquisa de 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, conforme mostrado no exemplo anterior. O GCS não tem pastas (algumas das ferramentas do GCS simulam pastas). Não é necessário criar ou manipular o prefixo usado pelo cache vcpkg.

Cache do GitHub Actions

Observação

Esta seção cobre um recurso experimental do vcpkg que pode ser alterado ou removido a qualquer momento.

x-gha[,<rw>]

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

Início rápido

Para que o vcpkg use o GitHub Actions Cache, ele precisa da URL do Cache de Ações e do Runtime Token. 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 GitHub Actions Cache só pode ser usado em um fluxo de trabalho do GitHub Actions.

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

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

Pacotes universais no Azure Artifacts

Observação

Esta seção cobre um recurso experimental do vcpkg que pode ser alterado ou removido a qualquer momento.

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

Adiciona Pacotes Universais no Azure Artifacts como um provedor.

Início rápido

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

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

Exemplo:

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

Forneça o parâmetro para fazer com que o project_name vcpkg baixe e publique Pacotes Universais em seu feed em um escopo de projeto.

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

Deixe o parâmetro vazio para fazer com que o project_name vcpkg baixe e publique Pacotes Universais em seu feed em um escopo de 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 do URL

O modelo usa chaves 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}

Aviso

Esse valor pode aparecer na linha de comando de chamadas de processo externo, o que pode ter implicações de segurança em seu ambiente.

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 da CLI do -Source NuGet:

nuget,<uri>[,<rw>]

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

nugetconfig,<path>[,<rw>]

Configure o tempo limite para fontes NuGet:

nugettimeout,<seconds>

Os arquivos de configuração devem definir a defaultPushSource para dar suporte à gravação de pacotes de volta no feed.

Credenciais

Muitos servidores NuGet exigem credenciais adicionais para acessar. A maneira mais flexível de fornecer credenciais é por meio da nugetconfig fonte com um arquivo personalizado nuget.config . 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 arquivo .nuget.config 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 o 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 por meio de mono via mono /path/to/nuget.exe sources add ....

metadata.repository

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

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

ou

    <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 vazias. Isso é usado especificamente para associar pacotes no GitHub Packages ao projeto de construção e não se destina a associar às fontes de pacote originais.

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ávelVCPKG_USE_NUGET_CACHE de ambiente como true (sem distinção entre maiúsculas e minúsculas) ou 1.

Exemplos de provedores

Se o sistema de CI de sua escolha não estiver listado, você pode enviar um PR para adicioná-lo!

GitHub Packages

Para usar o vcpkg com o GitHub Packages, é recomendável usar o provedor NuGet.

Observação

21/09/2020: os agentes hospedados do GitHub vêm com uma cópia mais antiga e pré-instalada do vcpkg no caminho que não dá suporte ao cache binário mais recente. Isso significa que chamadas diretas para bootstrap-vcpkg ou vcpkg sem um prefixo de caminho podem chamar uma instância vcpkg não intencional. Se você quiser usar sua própria cópia do vcpkg, siga as duas etapas a seguir para evitar problemas se quiser usar sua própria cópia do vcpkg:

  1. Execute o equivalente rm -rf "$VCPKG_INSTALLATION_ROOT" a usar shell: 'bash'.
  2. Sempre chame vcpkg e bootstrap-vcpkg com um prefixo de caminho, 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 }}

Se você estiver usando manifestos, poderá omitir a vcpkg package restore etapa: ela será executada automaticamente como parte do build.

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

Artefatos do Azure DevOps

Para usar o vcpkg com Azure DevOps Artifacts, é 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 de Configurações do Projeto ->Geral ->Visão Geral ->Azure DevOps Services>Artefatos.

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

Como usar 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, precisará instalar o Mono para executar nuget.exe (apt install mono-complete, brew install mono, etc).

Como usar 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 PAT (Token de Acesso Pessoal) como senha para segurança máxima. Você pode gerar um PAT em Configurações do usuário -> Tokens de acesso pessoal ou https://dev.azure.com/<ORG>/_usersSettings/tokens.

ABI Hash

Observação

As informações sobre o ABI Hash são fornecidas como uma nota de implementação e serão alteradas sem aviso prévio.

Para cada compilação, o vcpkg calcula um Hash ABI para determinar a equivalência. Se duas compilações tiverem o mesmo ABI Hash, 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 portas
  • O conteúdo e o nome do arquivo triplo
  • O arquivo executável do compilador C++
  • O arquivo executável do compilador C
  • O conjunto de recursos selecionados
  • O hash da ABI de cada dependência
  • Todas as funções auxiliares referenciadas por portfile.cmake (heurística)
  • A versão do CMake usada
  • O conteúdo de todas as variáveis de ambiente listadas em VCPKG_ENV_PASSTHROUGH
  • O conteúdo textual do arquivo do conjunto de ferramentas (VCPKG_CHAINLOAD_TOOLCHAIN_FILE)
  • O kit de ferramentas GRDK (somente quando direcionado à plataforma Xbox)

Apesar dessa 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 triplo 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 instalado atual para /share/<port>/vcpkg_abi_info.txt inspeção.

Exemplo de hash ABI de zlib

Habilite a saída de depuração para imprimir o hash completo da ABI (Interface Binária do Aplicativo) de um pacote. 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 hash bb1c96759ac96102b4b18215db138daedd3eb16c2cd3302ae7bffab2b643eb87 ABI para o pacote zlib é construído pelo hash de todas as informações relevantes possíveis para distinguir pacotes binários.

A versão do 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

Os arquivos relevantes, o compilador e as informações de versão da ferramenta são 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>

Observação

A triplet_abi entrada contém três hashes: o hash do conteúdo do arquivo do trigêmeo x86-windows , o windows.cmake conjunto de ferramentas e o hash do compilador. Esses hashes mudariam se você decidisse segmentar uma plataforma diferente.