Руководство по устранению неполадок версий

Статья
04/04/2024

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

Проверка файла версии для порта

Заметка

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

Чтобы проверить базу данных версий определенного порта, выполните следующие действия.

Перейдите в каталог vcpkg/versions.
Найдите папку порта:
- Найдите папку, соответствующую первой букве порта. Например, для fmt откройте папку с именем f-.
Откройте файл версии портов:
- Найдите JSON-файл с тем же именем порта. Например, файл версий fmt называется fmt.json.

Файл версии порта содержит список доступных версий с такой информацией, как теги версий и соответствующий хэш объекта дерева Git. Эти сведения требуются vcpkg для получения определенных версий портов. В ваших файлах манифеста можно использовать только версии, содержащиеся в этом списке.

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

Дополнительные сведения об использовании манифеста см. в разделе манифест.

Причина. Запрос несуществующей версии пакета

Если версия, указанная в файле манифеста, не существует в базе данных версии vcpkg, vcpkg не удается устранить зависимость и выдает сообщение об ошибке, напоминающее следующее:

error: no version database entry for fmt at 100.0.0
Available versions:
  10.1.1
  10.1.0
  10.0.0
  9.1.0#1
  9.1.0
  9.0.0
  8.1.1#2
  8.1.1#1
  ...
See `vcpkg help versioning` or https://learn.microsoft.com/vcpkg/users/versioning for more information.

Чтобы устранить проблему, выполните следующие действия.

Обновите базу данных версий:
- Нужная версия может не находиться в локальной копии базы данных версий. В этом случае выполните команду git pull, чтобы обновить реестр vcpkg до последнего коммита.
Проверьте доступные версии:
- Выберите одну из версий, доступных в базе данных версий.
Обновление файла манифеста:
- Измените файл vcpkg.json.
- Измените указанную версию на ту, которая доступна в репозитории vcpkg. Например, измените значение "версия>=": "100.0.0" на "version>=": "10.1.1".
Выполните установку vcpkg:
- Снова выполните команду vcpkg install в терминале или командной строке.

Причина: указание ограничения версии в разных форматах

Конфликт схемы версий возникает, когда версия, указанная в файле vcpkg.json для зависимости, использует другую схему управления версиями, отличную от используемой в базовой версии репозитория vcpkg. Это приводит к ошибке, так как vcpkg не может сравнивать версии в разных схемах.

Если объявленное ограничение version>= использует другую схему версий, отличную от используемой в базовой версии, vcpkg не может определить, какая версия больше или равна другой.

Например, если указать:

{
  "dependencies": [
    {
      "name": "boost-regex",
      "version>=": "1.75.0"
    }
  ]
}

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

error: version conflict on boost-regex:x64-windows:  required 1.75.0, which cannot be compared with the baseline version 1.83.0.

The versions have incomparable schemes:
  boost-regex@1.83.0 has scheme relaxed
  boost-regex@1.75.0 has scheme string

This can be resolved by adding an explicit override to the preferred version. For example:

  "overrides": [
    { "name": "boost-regex", "version": "1.83.0" }
  ]

See `vcpkg help versioning` or https://learn.microsoft.com/vcpkg/users/versioning for more information.

Резолюций:

Используйте совместимую схему версий:
- Проверьте базу данных версий в репозитории vcpkg в versions/b-/boost-regex.json, чтобы найти версию boost-regex, которая использует ту же схему управления версиями, что и базовая.
- Обновите ограничение version>= в vcpkg.json к версии, использующей совместимую схему.
Переопределите нужную версию:
- Если вам нужна определенная версия boost-regex, использующая другую схему управления версиями, ее можно переопределить в манифесте.
- Измените ваш vcpkg.json, чтобы он включал раздел с переопределениями, указывающий нужную версию.
```
{
  "dependencies": [
    { "name": "boost-regex" }
  ],
  "overrides": [
    { "name": "boost-regex", "version": "1.75.0" }
  ]
}
```

Причина: недостаточная история коммитов в неглубоком клоне

Если vcpkg клонируется с ограниченной историей коммитов (поверхностное клонирование), у него отсутствует необходимая история для разрешения определенных ограничений версий или базовых версий. Хэши деревьев Git, используемые vcpkg для получения определенных версий портов, доступны только после извлечения всей истории коммитов. vcpkg определяет, если он был клонирован в урезанный репозиторий, и показывает сообщение об ошибке, если не удается получить версию порта.

Например, использование vcpkg.json с определенным базовым уровнем, как указано ниже.

{
  "dependencies": [
    {
      "name": "fmt"
    }
  ],
  "overrides": [
    {
      "name": "fmt",
      "version": "7.1.3#1"
    }
  ],
  "builtin-baseline": "bb588985e37484d543fc849d0d79434e0d45bb3c"
}

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

error: failed to execute: "C:\Program Files\Git\cmd\git.exe" "--git-dir=C:\dev\demo\vcpkg\.git" "--work-tree=C:\dev\demo\vcpkg\buildtrees\versioning_\versions\fmt\4f8427eb0bd40da1856d4e67bde39a4fda689d72_26648.tmp" -c core.autocrlf=false read-tree -m -u 4f8427eb0bd40da1856d4e67bde39a4fda689d72
vcpkg was cloned as a shallow repository in: C:\dev\demo\vcpkg\.git
Try again with a full vcpkg clone.
error: git failed with exit code: (128).
fatal: failed to unpack tree object 4f8427eb0bd40da1856d4e67bde39a4fda689d72
note: while checking out port fmt with git tree 4f8427eb0bd40da1856d4e67bde39a4fda689d72

Эта ошибка указывает, что фиксация (4f8427eb0bd40da1856d4e67bde39a4fda689d72), необходимая для конкретной версии пакета fmt, недоступна в поверхностной копии.

Резолюций:

Преобразование в полный клон
- Самым простым решением этой проблемы является преобразование в полный клон:
```
git fetch --unshallow
```
Использование GitHub Actions (по умолчанию мелкие клоны)
- Действия GitHub часто по умолчанию используют поверхностные клоны. Чтобы обойти эту проблему, можно изменить рабочий процесс GitHub Actions для выполнения полного клона. Добавьте следующий шаг перед использованием vcpkg:
```
- name: Convert to Full Clone
  run: git fetch --unshallow
```

Причина: неожиданное включение функций по умолчанию в транзитивных зависимостях

При управлении зависимостями с помощью vcpkg можно обнаружить, что транзитивные зависимости устанавливаются с их функциями по умолчанию, даже если эти функции для проекта не нужны. Эта ситуация может привести к неожиданному увеличению объема или функциональности в конечной сборке.

Сценарий

У вас есть зависимость от библиотеки Y, которая, в свою очередь, зависит от библиотеки X. Библиотека X имеет функции по умолчанию, включая foo, которые необходимо исключить из проекта. Манифест верхнего уровня для библиотеки Y может выглядеть примерно так:

{
  "name": "my-project",
  "dependencies": [
    {
      "name": "Y",
      "features": ["featureB"],
      "default-features": false
    }
  ]
}

Ожидается, что X будет установлен без своих компонентов по умолчанию из-за настройки "default-features": false. Однако X по-прежнему устанавливается с функцией по умолчанию foo.

Причина

Свойство default-features рассматривается только в манифесте верхнего уровня. Это означает, что функции транзитивных зависимостей по умолчанию (например, X в этом сценарии) по-прежнему включены, если явно не отключены на верхнем уровне. При разрешении Y библиотеки vcpkg не распространяет параметр "default-features": false на транзитивную зависимость X, что приводит к установке X со своими функциями по умолчанию.

Резолюция

Чтобы обеспечить установку транзитивных зависимостей, таких как X без их компонентов по умолчанию, необходимо повысить их уровень до прямых зависимостей в манифесте верхнего уровня и явно отключить их функции по умолчанию. Измените vcpkg.json, чтобы непосредственно включить X с помощью "default-features": false.

{
  "name": "my-project",
  "dependencies": [
    {
      "name": "Y",
      "features": ["featureB"]
    },
    {
      "name": "X",
      "default-features": false
    }
  ]
}

Этот подход обеспечивает установку X без компонентов по умолчанию, так как теперь X является прямой зависимостью с явной инструкцией, чтобы исключить функции по умолчанию.

Более подробную информацию о том, как работают функции по умолчанию и как ими управлять, см. в статье о концепции функций по умолчанию.

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

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

Поделиться через