Руководство по устранению неполадок с двоичным кэшированием

Это руководство предназначено для пользователей с проблемами с двоичным кэшированием.

Включение сведений об отладке vcpkg

Настоятельно рекомендуется включить выходные данные отладки при выполнении этого руководства.

• Классический режим: добавьте --debug вызов команды.
• Цепочка инструментов CMake: добавьте -DVCPKG_INSTALL_OPTIONS="--debug" вызов или файл CMakePresets.json в CMake.
• MSBuild/Visual Studio: задайте для свойства VcpkgAdditionalInstallOptions значение --debug.
• Присвоение переменной среды VCPKG_INSTALL_OPTIONS значения --debug.

Отправка NuGet в {url} завершается ошибкой

При использовании двоичного источника NuGet появляется следующая ошибка:

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

При использовании двоичного источника конфигурации NuGet появляется следующая ошибка:

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

Эта ошибка возникает при попытке vcpkg и сбое использования командной строки NuGet для отправки пакетов в веб-канал NuGet.

Причина 1. Недостаточно разрешений на запись пользователей

Появится следующее сообщение об ошибке:

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

Отправка была отклонена удаленным источником, так как у пользователя нет достаточных разрешений на запись.

• Убедитесь, что у пользователя или группы пользователей есть разрешения на запись. В NuGet пользователь должен быть по крайней мере ролью участника в веб-канале.

Причина 2. Неправильно настроен url-адрес веб-канала NuGet

Может появиться ошибка:

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

Сервер отклонил push-запрос NuGet, так как он не распознал метод запроса.

• Убедитесь, что универсальный код ресурса (URI) в двоичном источнике является правильным и что он направляется к индексу службы веб-канала, как правило <feed base url>/nuget/v3/index.json.

Дополнительные ресурсы NuGet

Ознакомьтесь с документацией По NuGet, чтобы ознакомиться с рекомендациями по подключению к веб-каналу NuGet и публикации.

Ошибки отправки кэша

При отправке двоичного пакета в кэш возникают ошибки.

Причина 1. Не удалось отправить поставщик двоичного кэша

Отправка может завершиться ошибкой по различным причинам, и сообщения об ошибках обычно зависят от поставщика.

• Убедитесь, что вы прошли проверку подлинности в кэше. Разные поставщики проходят проверку подлинности по-разному.
• Проверьте, указан ли правильный универсальный код ресурса (URI) для кэша.
• Если вы используете NuGet в качестве двоичного источника, обратитесь к принудительному устранению неполадок.
• Ознакомьтесь с документацией или руководством по устранению неполадок конкретного поставщика.

Пустой двоичный кэш

Несмотря на отсутствие ошибок и успешной установки vcpkg, двоичный кэш остается пустым. При возникновении ошибок обратитесь к устранению неполадок NuGet и отправьте сведения об устранении неполадок для других поставщиков.

Причина 1. Vcpkg не имеет разрешений на запись в двоичный кэш

Следующее сообщение отсутствует в выходных данных.

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

Vcpkg пропускал отправку двоичного пакета в двоичный кэш.

• Убедитесь, что для конфигурации двоичного кэша задано write значение илиreadwrite

Перестроение библиотек вместо использования удаленного двоичного кэша

Система перестраивает библиотеки локально, даже если необходимый двоичный пакет доступен в удаленном двоичном кэше.

Следующее сообщение отсутствует в выходных данных.

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

Причина 1. Vcpkg не имеет разрешений на чтение из удаленного двоичного кэша

vcpkg выбирает чтение двоичного кэша по умолчанию по удаленному кэшу.

• Убедитесь, что для конфигурации двоичного кэша задано read значение илиreadwrite

Причина 2. Удаленный двоичный кэш пуст

Удаленный кэш должен содержать список отправленных двоичных пакетов.

• Ознакомьтесь с разделом пустого двоичного кэша .

Причина 3. Различия между локальными и удаленными средами сборки

Каждый пакет в двоичном кэше помечен хэшем ABI, который содержит версии компилятора, источники и другие сведения, чтобы различать двоичные пакеты. Если хэш ABI локально вычисляется не соответствует хранящейся удаленно, пакет не извлекается.

• Чтобы определить первопричину, обратитесь к руководству по устранению несоответствий ABI Hash.

Непредвиденные или частые перестроения библиотек

В неизменной среде и без обновления vcpkg вы по-прежнему находитесь в перестроении библиотек occassionally.

Причина 1. Незамеченные изменения в среде сборки

Каждый пакет в двоичном кэше помечен хэшем ABI, который содержит версии компилятора, источники и другие сведения, чтобы различать двоичные пакеты. Если хэш ABI локально вычисляется не соответствует хранящейся удаленно, пакет не извлекается.

• Чтобы определить первопричину, обратитесь к руководству по устранению несоответствий ABI Hash.

Устранение неполадок с несоответствием хэша ABI

Это руководство предназначено для пользователей для диагностики того, почему они имеют разные хэши ABI для двух идентичных двоичных пакетов.

Сравнение двух двоичных пакетов

Для определения разницы между двумя идентичными именованными пакетами требуется сравнение различных данных: источников, версий инструментов, компиляторов и целевых платформ. Хэш ABI предоставляет краткое представление этих данных. При вычислении хэша ABI vcpkg учитывает все соответствующие данные, включая содержимое файла, версии инструментов и сведения о системе. Он создает хэш для каждой точки данных, а затем объединяет эти хэши в одно значение двоичного пакета.

Сравнение хэшов двоичного пакета ABI

Хэш ABI библиотеки 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

Если хэш-изменения между запусками для одной библиотеки, это означает, что два пакета отличаются.

Сравнение хэша версии компилятора ABI

Проверьте, изменилась ли версия компилятора между выполнением.

[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

Хэш компилятора .f5d02a6542664cfbd4a38db478133cbb1a18f315

Сравнение хэш-записей ABI

Сравнение записей ABI для каждого пакета. Запись представляет часть информации, которая способствует окончательному хэшу.

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

Несоответствие 1. Файлы портов

Файлы портов включают скрипты портов (portfile.cmake, vcpkg.jsonфайлы*.patch исправлений) или любой другой файл в каталоге портов: ports/<library>/*

Причина 1. CI или конвейер обновил реестр портов

Перед запуском vcpkg в CI он клонировал последний репозиторий vcpkg.

• При использовании git clone https://github.com/microsoft/vcpkgbootstrap сценария убедитесь, что вы запустите определенную фиксацию.
• Рассмотрите возможность добавления vcpkg в качестве подмодулы Git в проект.

Причина 2. GitHub Actions обновлен vcpkg

Вы используете системную копию vcpkg, предоставляемую GitHub Actions, которая была обновлена.

• Клонируйте собственную копию vcpkg.
• Рекомендуется сделать vcpkg подмодулом Git в проекте.

Несоответствие 2: вспомогательные функции CMake vcpkg

Вспомогательные функции CMake находятся в каталоге скриптов: scripts/*и обычно начинаются с vcpkg_.

Причина 1. Обновленные вспомогательные скрипты CI или конвейера

Перед запуском vcpkg в CI он клонировал последний репозиторий vcpkg.

• При использовании git clone https://github.com/microsoft/vcpkgbootstrap сценария убедитесь, что вы запустите определенную фиксацию.
• Рассмотрите возможность добавления vcpkg в качестве подмодулы Git в проект.

Причина 2. GitHub Actions обновлен vcpkg

Вы используете системную копию vcpkg, предоставляемую GitHub Actions, которая была обновлена.

• Клонируйте собственную копию vcpkg.
• Рекомендуется сделать vcpkg подмодулом Git в проекте.

Несоответствие 3. Версия компилятора

vcpkg перестроил зависимости с другой версией компилятора.

Причина 1. Компилятор Visual Studio C++ автоматически обновляется.

Visual Studio автоматически обновляет рабочую нагрузку C++, включая компилятор, между запусками. Даже незначительные обновления версий приводят к перестроению набора библиотек vcpkg.

• Отключите автоматическое обновление компилятора.

Причина 2. Библиотека была создана на другом компьютере, чем на компьютере, используемом для его использования.

Один компьютер создал и опубликовал двоичный пакет в удаленный кэш. Другой компьютер, обычно используемый для разработки, использовал кэшированную библиотеку.

• Используйте ту же версию компилятора C++ локально, что и на удаленном компьютере. Для Visual Studio рассмотрим загрузчик фиксированной версии.
• Перестройте зависимости локально для целей разработки. Тестирование и устранение проблем позже во время непрерывной интеграции.

Причина 3. Локальное изображение обновило компилятор.

Базовый образ, используемый для создания зависимостей vcpkg, изменился, который обновил версию компилятора.

• Закрепление на стабильном и версивном изображении. Убедитесь, что вы не извлекаете последний образ, чтобы он не обновлял базовые средства или компиляторы между выполнением.
• Если вам нужно часто обновлять образ, закрепите средства компилятора C++ к определенной версии при создании образа.

Причина 4. GitHub Hosted Runners обновил базовый компилятор.

Размещенные GitHub runners обновляют компиляторы и средства еженедельно.

• В настоящее время невозможно исправить образ и предотвратить периодическое обновление средств и версий компилятора. Дополнительные варианты см. в разделе "Другие варианты " для альтернативных решений.

Несоответствие 4. Версия инструментов изменилась между выполнением.

Версия средств, используемых для создания библиотек, CMake или PowerShell, изменилась между выполнением.

Причина 1. Visual Studio автоматически обновляется.

Visual Studio автоматически обновляется, включая все средства между запусками. Даже незначительные обновления версий приводят к перестроению набора библиотек vcpkg.

• Отключите автоматические обновления Visual Studio.
• Добавьте --x-abi-tools-use-exact-versions вызов vcpkg. Это исправляет ABI ваших средств на основе версии в vcpkgTools.xml; vcpkg извлекает собственную копию при необходимости.

Причина 2. Библиотека была создана на другом компьютере, чем на компьютере, используемом для его использования.

Один компьютер создал и опубликовал двоичный пакет в удаленный кэш. Другой компьютер, обычно используемый для разработки, использовал кэшированную библиотеку.

• Используйте те же версии инструментов локально, что и на удаленном компьютере.
• Перестройте зависимости локально для целей разработки. Тестирование и устранение проблем позже во время непрерывной интеграции.
• Добавьте --x-abi-tools-use-exact-versions вызов vcpkg. Это исправляет ABI ваших средств на основе версии в vcpkgTools.xml; vcpkg извлекает собственную копию при необходимости.

Причина 3. Локальное изображение обновило средства.

Базовый образ, используемый для сборки зависимостей vcpkg, изменился, какие версии всех используемых средств.

• Закрепление на стабильном и версивном изображении. Убедитесь, что вы не извлекаете последний образ, чтобы он не обновлял базовые средства между выполнением.
• Если вам нужно часто обновлять образ, закрепите все соответствующие средства в определенной версии при создании образа.
• Добавьте --x-abi-tools-use-exact-versions вызов vcpkg. Это исправляет ABI ваших средств на основе версии в vcpkgTools.xml; vcpkg извлекает собственную копию при необходимости.

Причина 4. GitHub Hosted Runners обновил базовые средства.

Размещенные GitHub runners обновляют компиляторы и средства еженедельно.

• Добавьте --x-abi-tools-use-exact-versions вызов vcpkg. Это исправляет ABI ваших средств на основе версии в vcpkgTools.xml; vcpkg извлекает собственную копию при необходимости.

Другие параметры

Если указанные выше параметры не работают, рассмотрите следующие обходные пути.

• Используйте vcpkg export для создания автономного архива зависимостей вместо восстановления из манифеста.
• Рассмотрите возможность использования локального образа Docker для создания библиотек
• Выполнение вспомогательной непрерывной интеграции, которая создает библиотеки vcpkg на регулярной частоте (например, ежедневно или еженедельно)

Проблема не указана здесь

Если проблема не указана здесь, посетите наш репозиторий , чтобы создать новую проблему.