Configuração de cache binário
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
).
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.
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.
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 usandowrite
oureadwrite
)
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:
- 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.
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 /
.
files,<absolute path>[,<rw>]
Armazena arquivos compactados em zip no caminho com base na ID de cache binário.
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 /
.
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.
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.
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"
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.
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.
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
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
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.
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 ...
.
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.
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
.
Se o sistema de CI de sua escolha não estiver listado, você pode enviar um PR para adicioná-lo!
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:
- Execute o equivalente
rm -rf "$VCPKG_INSTALLATION_ROOT"
a usarshell: 'bash'
. - Sempre chame
vcpkg
ebootstrap-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 do build.
Consulte a documentação do NuGet do GitHub Packages para obter mais informações.
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.
# 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).
# 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
.
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.
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.
Comentários do vcpkg
O vcpkg é um projeto código aberto. Selecione um link para fornecer comentários: