Guide de résolution des problèmes liés au contrôle de version

Article
04/04/2024

Ce guide est destiné aux utilisateurs qui rencontrent des problèmes de contrôle de version.

Inspection du fichier de version d’un port

Remarque

Le processus décrit ci-dessous est destiné à fonctionner pour les ports du registre vcpkg. Consultez notre documentation sur le Registre pour découvrir comment la base de données de contrôle de version est implémentée dans les registres personnalisés.

Pour inspecter la base de données des versions d’un port spécifique :

Accédez au répertoire vcpkg/versions.
Recherchez le dossier du port :
- Recherchez le dossier correspondant à la première lettre du port. Par exemple, pour fmt ouvrir le dossier nommé f-.
Ouvrez le fichier de version des ports :
- Recherchez le fichier JSON portant le même nom que le port. Par exemple, le fmt fichier de versions est nommé fmt.json.

Le fichier de version du port contient une liste de versions disponibles avec des détails tels que les balises de version et leur hachage d’arborescence Git correspondant. Ces informations sont requises par vcpkg pour récupérer des versions de port spécifiques. Seules les versions contenues dans cette liste sont disponibles pour être utilisées dans vos fichiers manifestes.

Pour plus d’informations sur le contrôle de version, consultez notre documentation de référence :

Pour plus d’informations sur l’utilisation d’un manifeste, consultez le manifeste

Cause : Demande d’une version inexistante d’un package

Lorsqu’une version spécifiée dans le fichier manifeste n’existe pas dans la base de données de version vcpkg, vcpkg ne parvient pas à résoudre la dépendance et génère un message d’erreur semblable à ce qui suit :

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.

Pour résoudre le problème :

Mettez à jour la base de données des versions :
- La version souhaitée peut ne pas figurer dans votre copie locale de la base de données de versions. Dans ce cas, exécutez la git pull commande pour mettre à jour le registre vcpkg vers la dernière validation.
Vérifiez les versions disponibles :
- Choisissez l’une des versions disponibles dans la base de données de versions.
Mettre à jour le fichier manifeste :
- Modifiez votre vcpkg.json fichier.
- Remplacez la version spécifiée par une version disponible dans le référentiel vcpkg. Par exemple, passez de « version>= » : « 100.0.0 » à « version>= » : « 10.1.1 ».
Exécutez l’installation de vcpkg :
- Réexécutez la vcpkg install commande dans votre terminal ou invite de commandes.

Cause : Spécification d’une contrainte de version entre différents schémas

Un conflit de schémas de version se produit lorsque la version spécifiée dans le vcpkg.json fichier pour une dépendance utilise un schéma de gestion de version différent de celui utilisé dans la version de référence du référentiel vcpkg. Cela entraîne une erreur, car vcpkg ne peut pas comparer les versions entre différents schémas.

Si une contrainte déclarée version>= utilise un schéma de version différent de celui utilisé dans la version de référence, vcpkg ne peut pas déterminer quelle version est supérieure ou égale à l’autre.

Par exemple, si vous spécifiez :

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

vcpkg génère le message d’erreur suivant :

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.

Résolutions :

Utilisez un schéma de version compatible :
- Examinez la base de données de version dans le référentiel vcpkg sous versions/b-/boost-regex.json pour rechercher une version de celle-ci utilisant le même schéma de boost-regex contrôle de version que la base de référence.
- Mettez à jour la version>= contrainte dans votre vcpkg.json version qui utilise un schéma compatible.
Remplacez la version souhaitée :
- Si vous avez besoin d’une version spécifique de boost-regex qui utilise un autre schéma de contrôle de version, vous pouvez la remplacer dans votre manifeste.
- Modifiez votre vcpkg.json option pour inclure une section remplacements spécifiant la version souhaitée :
```
{
  "dependencies": [
    { "name": "boost-regex" }
  ],
  "overrides": [
    { "name": "boost-regex", "version": "1.75.0" }
  ]
}
```

Cause : Historique de validation insuffisant dans un clone peu profond

Lorsque vcpkg est cloné avec un historique de validation limité (clone peu profond), il manque l’historique de validation nécessaire pour résoudre des contraintes de version ou des lignes de base spécifiques. Les hachages d’arborescence Git utilisés par vcpkg pour récupérer des versions spécifiques de ports sont disponibles uniquement lorsque l’historique de validation complet est case activée eded. vcpkg détecte lorsqu’il a été cloné dans un référentiel peu profond et génère un message d’erreur lorsqu’il ne parvient pas à récupérer une version de port.

Par exemple, à l’aide d’une vcpkg.json base de référence spécifique comme suit :

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

L’erreur suivante se produit :

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

Cette erreur indique que la validation (4f8427eb0bd40da1856d4e67bde39a4fda689d72) requise pour la version spécifique du package fmt n’est pas disponible dans le clone peu profond.

Résolutions :

Convertir en clone complet
- La solution la plus simple à ce problème consiste à convertir en clone complet :
```
git fetch --unshallow
```
Utilisation de GitHub Actions (clones peu profonds par défaut)
- GitHub Actions est souvent défini par défaut sur des clones peu profonds. Pour contourner ce problème, vous pouvez modifier le flux de travail GitHub Actions pour effectuer un clone complet. Ajoutez l’étape suivante avant d’utiliser vcpkg :
```
- name: Convert to Full Clone
  run: git fetch --unshallow
```

Cause : inclusion inattendue des fonctionnalités par défaut dans les dépendances transitives

Lors de la gestion des dépendances avec vcpkg, vous pouvez constater que les dépendances transitives sont installées avec leurs fonctionnalités par défaut, même si vous ne souhaiterez peut-être pas ces fonctionnalités pour votre projet. Cette situation peut entraîner des ballonnements inattendus ou des fonctionnalités dans votre build finale.

Scénario

Vous avez une dépendance sur la bibliothèque Y, qui dépend à son tour de la bibliothèque X. La bibliothèque X a des fonctionnalités par défaut, notamment foo, que vous souhaitez exclure de votre projet. Votre manifeste de niveau supérieur pour la bibliothèque Y peut ressembler à ceci :

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

Vous vous attendez à ce qu’elle X soit installée sans ses fonctionnalités par défaut en raison du "default-features": false paramètre. Toutefois, X est toujours installé avec la fonctionnalité foopar défaut.

Motif

La default-features propriété est considérée uniquement au niveau du manifeste de niveau supérieur. Cela signifie que les fonctionnalités par défaut des dépendances transitives (comme X dans ce scénario) sont toujours incluses, sauf si elles sont explicitement désactivées au niveau supérieur. Lorsque la bibliothèque Y est résolue, vcpkg ne propage pas le "default-features": false paramètre à la dépendance Xtransitive, ce qui entraîne l’installation de X ses fonctionnalités par défaut.

Résolution

Pour vous assurer que les dépendances transitives comme celles-ci X sont installées sans leurs fonctionnalités par défaut, vous devez les promouvoir en dépendances directes dans votre manifeste de niveau supérieur et désactiver explicitement leurs fonctionnalités par défaut. Modifiez-la vcpkg.json pour inclure X directement avec "default-features": false:

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

Cette approche garantit l’installation X sans ses fonctionnalités par défaut, car il s’agit maintenant X d’une dépendance directe avec une instruction explicite pour exclure les fonctionnalités par défaut.

Pour plus d’informations sur le fonctionnement des fonctionnalités par défaut et leur gestion, consultez l’article sur le concept de fonctionnalités par défaut.

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.

Partager via