Guia de solução de problemas de cache binário

  • Artigo

Este guia destina-se a usuários com problemas com cache binário.

Habilitar informações de depuração vcpkg

É altamente recomendável que você habilite a saída de depuração ao seguir este guia.

  • Modo clássico: adicione --debug à sua chamada de comando.
  • Cadeia de ferramentas CMake: adicione -DVCPKG_INSTALL_OPTIONS="--debug" em sua chamada de configuração do CMake ou em seu CMakePresets.json arquivo.
  • MSBuild/Visual Studio: defina a propriedade VcpkgAdditionalInstallOptions como --debug.
  • Defina a variável de ambiente VCPKG_INSTALL_OPTIONS como --debug.

Falha no envio por push do NuGet para {url}

Importante

Atualize sua ferramenta vcpkg para a versão mais recente. Além disso, habilite a saída de depuração para logs de erros abrangentes.

Ao usar uma fonte binária NuGet, o seguinte erro aparece:

Pushing NuGet to {url} failed. Use --debug for more information.

Ao usar uma origem binária do arquivo de configuração NuGet, o seguinte erro aparece:

Pushing NuGet config to {url} failed. Use --debug for more information.

Esse erro surge quando vcpkg tenta e não consegue usar a linha de comando NuGet para carregar pacotes em um feed NuGet.

Causa 1: permissões de gravação de usuário insuficientes

Você encontrar a seguinte mensagem de erro:

System.Net.Http.HttpRequestException: Response status code does not indicate success: 403 (Forbidden - User <user> lacks permission to complete this action. You need to have 'AddPackage'.

O push foi rejeitado pela fonte remota porque o usuário não tem permissões de gravação suficientes.

  • Confirme se o usuário ou grupo de usuários tem permissões de gravação. No NuGet, o usuário deve ser pelo menos uma função de Colaborador para o feed.

Causa 2: URL do NuGet Feed configurado incorretamente

Você pode ver o erro:

System.Net.Http.HttpRequestException: Response status code does not indicate success: 405 (Method Not Allowed).

O servidor rejeitou a solicitação por push do NuGet porque não reconheceu o método de solicitação.

  • Verifique se o URI na origem binária está correto e se ele direciona para o índice de serviço do feed, normalmente <feed base url>/nuget/v3/index.json.

Recursos adicionais do NuGet

Consulte a documentação do NuGet para obter diretrizes sobre como se conectar e publicar em um feed NuGet.

Erros de carregamento de cache

Importante

Atualize sua ferramenta vcpkg para a versão mais recente. Além disso, habilite a saída de depuração para logs de erros abrangentes.

Você encontra erros ao carregar um pacote binário para o cache.

Causa 1: Falha ao carregar o provedor de cache binário

Os carregamentos podem falhar por vários motivos, e as mensagens de erro geralmente são específicas do provedor.

  • Verifique se você está autenticado no cache. Provedores diferentes se autenticam de forma diferente.
  • Verifique se você especificou o URI correto para seu cache.
  • Consulte a solução de problemas por push se você estiver usando o NuGet como uma fonte binária.
  • Revise a documentação ou o guia de solução de problemas do seu provedor específico.

Cache binário vazio

Importante

Atualize sua ferramenta vcpkg para a versão mais recente. Além disso, habilite a saída de depuração para logs de erros abrangentes.

Embora você não tenha encontrado erros e a instalação do vcpkg tenha sido bem-sucedida, o cache binário permanece vazio. Se você observou erros, consulte a solução de problemas por push para o NuGet e a solução de problemas de upload para outros provedores.

Causa 1: vcpkg não tem permissões de gravação no cache binário

A seguinte mensagem está ausente na saída.

Uploading binaries for 'rapidjson:x64-windows' to <binary source> source <url>.
Stored binaries in 1 destinations in 1.5 s.

vcpkg ignorou o upload do pacote binário para seu cache binário.

  • Verifique se a configuração do cache binário está definida como write oureadwrite

As bibliotecas são reconstruídas em vez de usar o cache binário remoto

Importante

Atualize sua ferramenta vcpkg para a versão mais recente. Além disso, habilite a saída de depuração para logs de erros abrangentes.

Seu sistema reconstrói bibliotecas localmente, mesmo quando o pacote binário necessário está disponível no cache binário remoto.

A seguinte mensagem está ausente na saída.

Restored 1 package(s) from <remote binary cache> in 1.1 s. Use --debug to see more details.

Causa 1: vcpkg não tem permissões de leitura do cache binário remoto

vcpkg optar por ler seu cache binário padrão sobre o remoto.

  • Verifique se a configuração do cache binário está definida como read oureadwrite

Causa 2: O cache binário remoto está vazio

O cache remoto deve conter uma lista de pacotes binários que você enviou.

  • Consulte a seção de cache binário vazio.

Causa 3: Diferenças entre ambientes de compilação locais e remotos

Cada pacote no cache binário é rotulado com um hash ABI que contém versões do compilador, fontes e outras informações para distinguir entre pacotes binários. Se o hash ABI computado localmente não corresponder ao armazenado remotamente, o pacote não será recuperado.

Reconstruções de bibliotecas inesperadas ou frequentes

Importante

Atualize sua ferramenta vcpkg para a versão mais recente. Além disso, habilite a saída de depuração para logs de erros abrangentes.

Em um ambiente inalterado e sem atualizar o vcpkg, você ainda se encontra reconstruindo bibliotecas occassionalmente.

Causa 1: alterações não detectadas no ambiente de compilação

Cada pacote no cache binário é rotulado com um hash ABI que contém versões do compilador, fontes e outras informações para distinguir entre pacotes binários. Se o hash ABI computado localmente não corresponder ao armazenado remotamente, o pacote não será recuperado.

Solução de problemas de incompatibilidade de hash ABI

Importante

Atualize sua ferramenta vcpkg para a versão mais recente. Além disso, habilite a saída de depuração para logs de erros abrangentes.

Este guia destina-se aos usuários para diagnosticar por que eles têm hashes ABI diferentes para dois pacotes binários de nome idêntico.

Comparando dois pacotes binários

Determinar a diferença entre dois pacotes com nomes idênticos requer a comparação de vários dados: fontes, versões de ferramentas, compiladores e plataformas de destino. O hash ABI fornece uma representação concisa desses dados. Ao calcular um hash ABI, vcpkg considera todos os dados relevantes, incluindo conteúdo do arquivo, versões da ferramenta e detalhes do sistema. Ele cria um hash para cada ponto de dados e, em seguida, combina esses hashes em um único valor para o pacote binário.

Comparação de hash ABI do pacote binário

O hash ABI da biblioteca zlib é bb1c96759ac96102b4b18215db138daedd3eb16c2cd3302ae7bffab2b643eb87:

[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

Se o hash for alterado entre execuções para a mesma biblioteca, isso indica que os dois pacotes são distintos.

Comparação de hash ABI da versão do compilador

Verifique se a versão do compilador foi alterada entre as execuções.

[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

O hash do compilador é f5d02a6542664cfbd4a38db478133cbb1a18f315.

Comparação de entrada de hash ABI

Compare as entradas ABI para cada pacote. Uma entrada representa uma informação que contribui para o hash 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.

Incompatibilidade 1: Arquivos de porta

Os arquivos de porta incluem scripts de porta (portfile.cmake, vcpkg.json), arquivos de patch (*.patch) ou qualquer outro arquivo no diretório de portas: ports/<library>/*.

Causa 1: CI ou pipeline atualizado o registro da porta

Antes do vcpkg ser executado em seu CI, ele clonava o repositório vcpkg mais recente.

  • Ao usar git clone https://github.com/microsoft/vcpkg seguido pelo script, certifique-se de bootstrap fazer check-out para uma confirmação específica.
  • Considere adicionar vcpkg como um submódulo git ao seu projeto.

Causa 2: Ações do GitHub atualizadas vcpkg

Você está usando a cópia do sistema do vcpkg fornecida pelo GitHub Actions, que foi atualizada.

  • Clone sua própria cópia do vcpkg.
  • Considere tornar vcpkg um submódulo git em seu projeto.

Incompatibilidade 2: funções auxiliares do CMake vcpkg

As funções auxiliares do CMake residem no diretório scripts: scripts/*, e normalmente começam com vcpkg_.

Causa 1: scripts auxiliares atualizados de CI ou pipeline

Antes do vcpkg ser executado em seu CI, ele clonava o repositório vcpkg mais recente.

  • Ao usar git clone https://github.com/microsoft/vcpkg seguido pelo script, certifique-se de bootstrap fazer check-out para uma confirmação específica.
  • Considere adicionar vcpkg como um submódulo git ao seu projeto.

Causa 2: Ações do GitHub atualizadas vcpkg

Você está usando a cópia do sistema do vcpkg fornecida pelo GitHub Actions, que foi atualizada.

  • Clone sua própria cópia do vcpkg.
  • Considere tornar vcpkg um submódulo git em seu projeto.

Incompatibilidade 3: Versão do compilador

vcpkg reconstruiu suas dependências com uma versão diferente do compilador.

Causa 1: O compilador do Visual Studio C++ atualizado automaticamente.

O Visual Studio atualizou automaticamente a carga de trabalho C++, incluindo o compilador, entre as execuções. Mesmo pequenas atualizações de versão resultarão na reconstrução do conjunto de bibliotecas do vcpkg.

Causa 2: A biblioteca foi criada em uma máquina diferente da máquina usada para consumi-la.

Uma máquina criou e publicou o pacote binário em um cache remoto. Outra máquina normalmente usada para desenvolvimento consumia a biblioteca armazenada em cache.

  • Use a mesma versão do compilador C++ localmente como em sua máquina remota. Para Visual Studio, considere um bootstrapper de versão fixa.
  • Reconstrua suas dependências localmente para fins de desenvolvimento. Teste e resolva problemas posteriormente durante a integração contínua.

Causa 3: A imagem auto-hospedada atualizou o compilador.

A imagem subjacente usada para criar dependências vcpkg foi alterada, o que atualizou a versão do compilador.

  • Fixe em uma imagem estável e versionada. Certifique-se de que você não está buscando a imagem mais recente para que ela não atualize automaticamente as ferramentas subjacentes ou compiladores entre as execuções.
  • Se você precisar atualizar a imagem com frequência, fixe as ferramentas do compilador C++ em uma versão específica ao criar sua imagem.

Causa 4: O GitHub Hosted Runners atualizou o compilador subjacente.

Os corredores hospedados do GitHub atualizam compiladores e ferramentas semanalmente.

  • Atualmente, não há como corrigir sua imagem e impedir que as ferramentas e a versão do compilador sejam atualizadas periodicamente. Consulte a seção de outras opções para obter soluções alternativas.

Incompatibilidade 4: A versão das ferramentas mudou entre as execuções.

A versão das ferramentas usadas para criar suas bibliotecas, CMake ou PowerShell, mudou entre as execuções.

Causa 1: Visual Studio atualizado automaticamente.

Visual Studio atualizado automaticamente, incluindo quaisquer ferramentas, entre execuções. Mesmo pequenas atualizações de versão resultarão na reconstrução do conjunto de bibliotecas do vcpkg.

  • Desative as atualizações automáticas do Visual Studio.
  • Adicione --x-abi-tools-use-exact-versions à sua chamada vcpkg. Isso corrige o ABI de suas ferramentas com base na versão em vcpkgTools.xml; vcpkg busca sua própria cópia, se necessário.

Causa 2: A biblioteca foi criada em uma máquina diferente da máquina usada para consumi-la.

Uma máquina criou e publicou o pacote binário em um cache remoto. Outra máquina normalmente usada para desenvolvimento consumia a biblioteca armazenada em cache.

  • Use as mesmas versões de ferramentas localmente que em sua máquina remota.
  • Reconstrua suas dependências localmente para fins de desenvolvimento. Teste e resolva problemas posteriormente durante a integração contínua.
  • Adicione --x-abi-tools-use-exact-versions à sua chamada vcpkg. Isso corrige o ABI de suas ferramentas com base na versão em vcpkgTools.xml; vcpkg busca sua própria cópia, se necessário.

Causa 3: A imagem auto-hospedada atualizou as ferramentas.

A imagem subjacente que você usou para criar dependências vcpkg foi alterada, que as versões de quaisquer ferramentas usadas.

  • Fixe em uma imagem estável e versionada. Verifique se você não está buscando a imagem mais recente para que ela não atualize automaticamente as ferramentas subjacentes entre as execuções.
  • Se você precisar atualizar a imagem com frequência, fixe todas as ferramentas relevantes em uma versão específica ao criar sua imagem.
  • Adicione --x-abi-tools-use-exact-versions à sua chamada vcpkg. Isso corrige o ABI de suas ferramentas com base na versão em vcpkgTools.xml; vcpkg busca sua própria cópia, se necessário.

Causa 4: Os Hosted Runners do GitHub atualizaram as ferramentas subjacentes.

Os corredores hospedados do GitHub atualizam compiladores e ferramentas semanalmente.

  • Adicione --x-abi-tools-use-exact-versions à sua chamada vcpkg. Isso corrige o ABI de suas ferramentas com base na versão em vcpkgTools.xml; vcpkg busca sua própria cópia, se necessário.

Outras opções

Se as opções acima não funcionarem, considere as seguintes soluções alternativas:

  • Use vcpkg export para produzir um arquivo autônomo de suas dependências em vez de restaurá-las a partir de um manifesto.
  • Considere o uso de uma imagem auto-hospedada do Docker para criar suas bibliotecas
  • Tenha uma execução de integração contínua auxiliar que construa bibliotecas vcpkg em uma cadência regular (por exemplo, diária ou semanal)

O problema não está listado aqui

Se o seu problema não estiver listado aqui, visite nosso repositório para criar um novo problema.