Referência de cache binário

Artigo
05/29/2024

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

Formulário	Descrição
`clear`	Desabilitar 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 origem baseada em arquivo NuGet-config; equivalente ao `-Config` parâmetro da CLI NuGet.
`nugettimeout,<seconds>`	Especifica um tempo limite para operações de rede NuGet; equivalente ao `-Timeout` parâmetro da CLI 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 origem 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 de Ações do GitHub como origem.
`interactive`	Habilita o gerenciamento interativo de credenciais para o 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 compilações sob demanda serão carregadas nesse remoto (write) ou ambas (readwrite).

Provedores

Provedor do AWS S3

Observação

Esta seção cobre uma característica experimental do vcpkg que pode mudar ou ser removida a qualquer momento.

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 Blobs do Azure

Observação

Esta seção cobre uma característica experimental do vcpkg que pode mudar ou ser removida 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 Assinatura de Acesso Compartilhado (SAS), que pode ser feita a partir da conta de armazenamento em Configurações - Assinatura de> Acesso Compartilhado. Este SAS necessitará:

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 de blob mais o contêiner deve ser passado 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 as operações normais, no entanto:

Será impresso na íntegra se --debug for aprovado
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 Tencent Cloud Object Storage

Observação

Esta seção cobre uma característica experimental do vcpkg que pode mudar ou ser removida a qualquer momento.

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

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

Provedor de arquivos

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

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

Provedor do Google Cloud Storage

Observação

Esta seção cobre uma característica experimental do vcpkg que pode mudar ou ser removida a qualquer momento.

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

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

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 deste guia de início rápido, você teria configurado a ferramenta de linha de comando para se autenticar com o gsutil Google Cloud. vcpkg usará essa ferramenta de linha de comando, portanto, certifique-se de que ela esteja em 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 do GCS simulam pastas). Não é necessário criar ou manipular o prefixo usado pelo cache vcpkg.

Cache de ações do GitHub

Observação

Esta seção cobre uma característica experimental do vcpkg que pode mudar ou ser removida a qualquer momento.

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 ACTIONS_CACHE_URLACTIONS_RUNTIME_TOKEN variáveis e de ambiente sejam definidas. A configuração correta dessas variáveis de ambiente é abordada na seção Guia de início rápido a seguir.

Início rápido

Para que o vcpkg use o 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 GitHub Actions Cache só pode ser usado a partir de um fluxo de trabalho do GitHub Actions.

Depois que as variáveis de ambiente tiverem sido exportadas, vcpkg poderá 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"

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 colchetes para expansão variável. Você pode usar as variáveis 'nome', 'versão', '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 -Source parâmetro NuGet CLI:

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 do NuGet:

nugettimeout,<seconds>

Os arquivos de configuração devem definir um defaultPushSource para oferecer suporte à gravação de pacotes de volta ao feed.

Credenciais

Muitos servidores NuGet exigem credenciais adicionais para acessar. A maneira mais flexível de fornecer credenciais é por meio da nugetconfig origem 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 padrão nuget.configdo 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 depois 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

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 e nugetconfig source respeitam certas 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}"/>

    <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 em Pacotes do GitHub com o projeto de compilação 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 origem 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 seu sistema de IC de escolha não estiver listado, você está convidado a enviar um PR para adicioná-lo!

GitHub Packages

Para usar vcpkg com pacotes GitHub, é 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 oferece 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, as duas etapas a seguir para evitar problemas se você quiser usar sua própria cópia do vcpkg:

Execute o equivalente rm -rf "$VCPKG_INSTALLATION_ROOT" a usar shell: 'bash'o .
Sempre chame vcpkg e bootstrap-vcpkg com um prefixo de caminho, como ./vcpkg, vcpkg/vcpkg, .\bootstrap-vcpkg.bat, etc.

# 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 da compilação.

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

Artefatos de DevOps do Azure

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 de Configurações do Projeto ->Geral ->Visão Geral ->Artefatos dos Serviços>de DevOps do Azure.

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

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, será necessário 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 Personal Access Token (PAT) como senha para segurança máxima. Você pode gerar um PAT em Configurações do Usuário - Tokens de> Acesso Pessoais 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, vcpkg calcula um Hash ABI para determinar a equivalência. Se duas compilações tiverem o mesmo Hash ABI, vcpkg as considerará idênticas e reutilizará os binários em projetos e máquinas.

O ABI Hash considera:

Cada arquivo 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 selecionados
O hash 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 quaisquer variáveis de ambiente listadas em VCPKG_ENV_PASSTHROUGH
Conteúdo textual do arquivo toolchain (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 você precisa rastrear para seu ambiente, você pode gerar um arquivo triplet 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 de hash ABI do zlib

Habilite a saída de depuração para imprimir o hash completo da Interface Binária de 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 hashbb1c96759ac96102b4b18215db138daedd3eb16c2cd3302ae7bffab2b643eb87 ABI para o pacote zlib é construído por hashing 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 hashed 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 x86-windows triplet, o windows.cmake toolchain e o hash do compilador. Esses hashes mudariam se você decidisse segmentar uma plataforma diferente.

Compartilhar via

Referência de cache binário

Sintaxe de configuração

Provedores

Provedor do AWS S3

Provedor de Armazenamento de Blobs do Azure

Início rápido

Provedor Tencent Cloud Object Storage

Provedor de arquivos

Provedor do Google Cloud Storage

Início rápido

Cache de ações do GitHub

Início rápido

Provedor HTTP

Modelo do URL

Cabeçalho

Provedor NuGet

Credenciais

`metadata.repository`

NuGet Cache

Exemplos de provedores

GitHub Packages

Artefatos de DevOps do Azure

Usando o feed de um pipeline

Usando o feed localmente

ABI Hash

Exemplo de hash ABI do zlib

Comentários

Recursos adicionais