Guide de résolution des problèmes de mise en cache binaire

Ce guide est destiné aux utilisateurs qui rencontrent des problèmes de mise en cache binaire.

Activer les informations de débogage vcpkg

Il est vivement recommandé d’activer la sortie de débogage lorsque vous suivez ce guide.

• Mode classique : ajoutez --debug à votre appel de commande.
• Chaîne d’outils CMake : ajoutez -DVCPKG_INSTALL_OPTIONS="--debug" votre appel de configuration CMake ou dans votre CMakePresets.json fichier.
• MSBuild/Visual Studio : définissez la propriété VcpkgAdditionalInstallOptions sur --debug.
• Définissez la variable d’environnement VCPKG_INSTALL_OPTIONS sur --debug.

Échec de l’envoi push NuGet vers {url}

Lorsque vous utilisez une source binaire NuGet, l’erreur suivante s’affiche :

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

Lorsque vous utilisez une source binaire de fichier de configuration NuGet, l’erreur suivante s’affiche :

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

Cette erreur se produit lorsque vcpkg tente et ne parvient pas à utiliser la ligne de commande NuGet pour charger des packages dans un flux NuGet.

Cause 1 : Autorisations d’écriture utilisateur insuffisantes

Vous rencontrez le message d’erreur suivant :

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

L’envoi a été rejeté par la source distante, car l’utilisateur n’a pas d’autorisations d’écriture suffisantes.

• Vérifiez que votre utilisateur ou groupe d’utilisateurs dispose d’autorisations d’écriture. Dans NuGet, l’utilisateur doit avoir au moins un rôle Contributeur au flux.

Cause 2 : URL de flux NuGet mal configurée

L’erreur peut s’afficher :

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

Le serveur a rejeté la requête Push de NuGet, car il n’a pas reconnu la méthode de requête.

• Vérifiez que l’URI de votre source binaire est correct et qu’il dirige vers l’index de service du flux, généralement <feed base url>/nuget/v3/index.json.

Ressources NuGet supplémentaires

Consultez la documentation NuGet pour obtenir des instructions sur la connexion et la publication sur un flux NuGet.

Erreurs de chargement du cache

Vous rencontrez des erreurs lors du chargement d’un package binaire dans votre cache.

Cause 1 : Échec du chargement du fournisseur de cache binaire

Les chargements peuvent échouer pour diverses raisons, et les messages d’erreur sont généralement spécifiques au fournisseur.

• Vérifiez que vous êtes authentifié auprès de votre cache. Différents fournisseurs s’authentifient différemment.
• Vérifiez si vous avez spécifié l’URI approprié pour votre cache.
• Reportez-vous à la résolution des problèmes push si vous utilisez NuGet comme source binaire.
• Passez en revue la documentation ou le guide de résolution des problèmes de votre fournisseur spécifique.

Cache binaire vide

Même si vous n’avez rencontré aucune erreur et que l’installation de vcpkg a réussi, le cache binaire reste vide. Si vous avez observé des erreurs, consultez la résolution des problèmes push pour NuGet et la résolution des problèmes de chargement pour d’autres fournisseurs.

Cause 1 : vcpkg ne dispose pas d’autorisations d’écriture dans le cache binaire

Le message suivant est manquant dans votre sortie.

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

vcpkg a ignoré le chargement du package binaire dans votre cache binaire.

• Vérifiez que votre configuration de cache binaire est définie sur write ou readwrite

Les bibliothèques sont régénérées au lieu d’utiliser le cache binaire distant

Votre système reconstruit les bibliothèques localement, même lorsque le package binaire requis est disponible dans le cache binaire distant.

Le message suivant est manquant dans votre sortie.

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

Cause 1 : vcpkg ne dispose pas d’autorisations de lecture à partir du cache binaire distant

vcpkg choisit de lire votre cache binaire par défaut sur le cache distant.

• Vérifiez que votre configuration de cache binaire est définie sur read ou readwrite

Cause 2 : Le cache binaire distant est vide

Le cache distant doit contenir une liste de packages binaires que vous avez envoyés (push).

• Reportez-vous à la section de cache binaire vide.

Cause 3 : Différences entre les environnements de build locaux et distants

Chaque package dans le cache binaire est étiqueté avec un hachage ABI qui contient des versions du compilateur, des sources et d’autres informations pour faire la distinction entre les packages binaires. Si le hachage ABI calculé localement ne correspond pas à celui stocké à distance, le package n’est pas récupéré.

• Consultez le guide de résolution des problèmes de non-correspondance de hachage ABI pour déterminer la cause racine.

Reconstructions inattendues ou fréquentes de la bibliothèque

Dans un environnement inchangé et sans mettre à jour vcpkg, vous vous retrouvez toujours à reconstruire des bibliothèques de façon occassionally.

Cause 1 : Modifications non détectées dans l’environnement de build

Chaque package dans le cache binaire est étiqueté avec un hachage ABI qui contient des versions du compilateur, des sources et d’autres informations pour faire la distinction entre les packages binaires. Si le hachage ABI calculé localement ne correspond pas à celui stocké à distance, le package n’est pas récupéré.

• Consultez le guide de résolution des problèmes de non-correspondance de hachage ABI pour déterminer la cause racine.

Résolution des problèmes d’incompatibilité de hachage ABI

Ce guide est destiné aux utilisateurs pour diagnostiquer pourquoi ils ont des hachages ABI différents pour deux packages binaires nommés identiquement.

Comparaison de deux packages binaires

La détermination de la différence entre deux packages nommés identiquement nécessite de comparer différentes données : sources, versions d’outils, compilateurs et plateformes cibles. Le hachage ABI fournit une représentation concise de ces données. Lors du calcul d’un hachage ABI, vcpkg considère toutes les données pertinentes, notamment le contenu du fichier, les versions d’outils et les détails système. Il crée un hachage pour chaque point de données, puis combine ces hachages en une seule valeur pour le package binaire.

Comparaison de hachage ABI du package binaire

Le hachage ABI de la bibliothèque zlib est 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

Si le hachage change entre les exécutions de la même bibliothèque, cela indique que les deux packages sont distincts.

Comparaison de hachage ABI version du compilateur

Vérifiez si la version de votre compilateur a changé entre les exécutions.

[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

Le hachage du compilateur est f5d02a6542664cfbd4a38db478133cbb1a18f315.

Comparaison des entrées de hachage ABI

Comparez les entrées ABI pour chaque package. Une entrée représente une information qui contribue au hachage 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>

Incompatibilité 1 : Fichiers de port

Les fichiers de port incluent des scripts de port (portfile.cmake, ), vcpkg.jsondes fichiers correctifs (*.patch) ou tout autre fichier dans le répertoire des ports : ports/<library>/*.

Cause 1 : CI ou pipeline mis à jour le registre de ports

Avant que vcpkg n’a été exécuté dans votre CI, il a cloné le dernier référentiel vcpkg.

• Lors de l’utilisation git clone https://github.com/microsoft/vcpkgbootstrap du script, vérifiez que vous accédez à une validation spécifique.
• Envisagez d’ajouter vcpkg en tant que sous-module git à votre projet.

Cause 2 : GitHub Actions mis à jour vcpkg

Vous utilisez la copie système de vcpkg fournie par GitHub Actions, qui a été mise à jour.

• Clonez votre propre copie de vcpkg.
• Envisagez de rendre vcpkg un sous-module git dans votre projet.

Incompatibilité 2 : fonctions d’assistance CMake vcpkg

Les fonctions d’assistance CMake résident dans le répertoire des scripts : scripts/*et commencent généralement par vcpkg_.

Cause 1 : Scripts d’assistance mis à jour par CI ou pipeline

Avant que vcpkg n’a été exécuté dans votre CI, il a cloné le dernier référentiel vcpkg.

• Lors de l’utilisation git clone https://github.com/microsoft/vcpkgbootstrap du script, vérifiez que vous accédez à une validation spécifique.
• Envisagez d’ajouter vcpkg en tant que sous-module git à votre projet.

Cause 2 : GitHub Actions mis à jour vcpkg

Vous utilisez la copie système de vcpkg fournie par GitHub Actions, qui a été mise à jour.

• Clonez votre propre copie de vcpkg.
• Envisagez de rendre vcpkg un sous-module git dans votre projet.

Incompatibilité 3 : version du compilateur

vcpkg reconstruit vos dépendances avec une autre version du compilateur.

Cause 1 : Le compilateur Visual Studio C++ est automatiquement mis à jour.

Visual Studio a automatiquement mis à jour la charge de travail C++, y compris le compilateur, entre les exécutions. Même les mises à jour de version mineures entraînent la reconstruction de l’ensemble de bibliothèques vcpkg.

• Désactivez les mises à jour automatiques du compilateur.

Cause 2 : La bibliothèque a été créée sur un ordinateur différent de celui utilisé pour l’utiliser.

Une machine a créé et publié le package binaire dans un cache distant. Un autre ordinateur généralement utilisé pour le développement a consommé la bibliothèque mise en cache.

• Utilisez la même version du compilateur C++ localement que sur votre ordinateur distant. Pour Visual Studio, envisagez un programme d’amorçage de version fixe.
• Régénérez vos dépendances localement à des fins de développement. Testez et résolvez les problèmes plus tard lors de l’intégration continue.

Cause 3 : L’image auto-hébergée a mis à jour le compilateur.

L’image sous-jacente que vous avez utilisée pour générer des dépendances vcpkg a changé, qui a mis à jour la version du compilateur.

• Épingler à une image stable et avec version. Vérifiez que vous ne récupérez pas la dernière image afin qu’elle ne met pas automatiquement à jour les outils ou les compilateurs sous-jacents entre les exécutions.
• Si vous devez fréquemment mettre à jour l’image, épinglez les outils du compilateur C++ à une version spécifique lors de la création de votre image.

Cause 4 : GitHub Hosted Runners a mis à jour le compilateur sous-jacent.

Les exécuteurs GitHub hébergés mettent à jour les compilateurs et les outils hebdomadaires.

• Actuellement, il n’existe aucun moyen de corriger votre image et d’empêcher la mise à jour périodique des outils et de la version du compilateur. Consultez la section d’autres options pour obtenir d’autres solutions.

Incompatibilité 4 : La version des outils a changé entre les exécutions.

La version des outils utilisés pour générer vos bibliothèques, CMake ou PowerShell, a changé entre les exécutions.

Cause 1 : Visual Studio est automatiquement mis à jour.

Visual Studio a automatiquement mis à jour, y compris tous les outils, entre les exécutions. Même les mises à jour de version mineures entraînent la reconstruction de l’ensemble de bibliothèques vcpkg.

• Désactivez les mises à jour automatiques de Visual Studio.
• Ajoutez --x-abi-tools-use-exact-versions à votre appel vcpkg. Cela corrige l’ABI de vos outils en fonction de la version dans vcpkgTools.xml; vcpkg récupère sa propre copie si nécessaire.

Cause 2 : La bibliothèque a été créée sur un ordinateur différent de celui utilisé pour l’utiliser.

Une machine a créé et publié le package binaire dans un cache distant. Un autre ordinateur généralement utilisé pour le développement a consommé la bibliothèque mise en cache.

• Utilisez les mêmes versions d’outils localement que sur votre ordinateur distant.
• Régénérez vos dépendances localement à des fins de développement. Testez et résolvez les problèmes plus tard lors de l’intégration continue.
• Ajoutez --x-abi-tools-use-exact-versions à votre appel vcpkg. Cela corrige l’ABI de vos outils en fonction de la version dans vcpkgTools.xml; vcpkg récupère sa propre copie si nécessaire.

Cause 3 : Image auto-hébergée mise à jour des outils.

L’image sous-jacente que vous avez utilisée pour générer des dépendances vcpkg a changé, que les versions des outils utilisés.

• Épingler à une image stable et avec version. Vérifiez que vous ne récupérez pas la dernière image afin qu’elle ne met pas automatiquement à jour les outils sous-jacents entre les exécutions.
• Si vous devez fréquemment mettre à jour l’image, épinglez tous les outils pertinents à une version spécifique lors de la création de votre image.
• Ajoutez --x-abi-tools-use-exact-versions à votre appel vcpkg. Cela corrige l’ABI de vos outils en fonction de la version dans vcpkgTools.xml; vcpkg récupère sa propre copie si nécessaire.

Cause 4 : GitHub Hosted Runners a mis à jour les outils sous-jacents.

Les exécuteurs GitHub hébergés mettent à jour les compilateurs et les outils hebdomadaires.

• Ajoutez --x-abi-tools-use-exact-versions à votre appel vcpkg. Cela corrige l’ABI de vos outils en fonction de la version dans vcpkgTools.xml; vcpkg récupère sa propre copie si nécessaire.

Autres options

Si les options ci-dessus ne fonctionnent pas, tenez compte des solutions de contournement suivantes :

• Permet vcpkg export de produire une archive autonome de vos dépendances au lieu de les restaurer à partir d’un manifeste.
• Envisagez d’utiliser une image auto-hébergée Docker pour créer vos bibliothèques
• Avoir une exécution d’intégration continue auxiliaire qui génère des bibliothèques vcpkg à une cadence régulière (par exemple, quotidienne ou hebdomadaire)

Le problème n’est pas répertorié ici

Si votre problème n’est pas répertorié ici, visitez notre référentiel pour créer un problème.