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

Article
02/11/2025

Ce guide est destiné aux utilisateurs qui rencontrent des problèmes liés à la gestion des versions de .

Inspection du fichier de version d’un port

Remarque

Le processus décrit ci-dessous est destiné à fonctionner pour les ports à partir du registre vcpkg . Consultez notre documentation registre pour savoir 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 fichier de versions fmt est nommé fmt.json.

Le fichier de version du port contient une liste des versions disponibles avec des détails tels que les balises de version et leur hachage d’objet 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 :

concepts de gestion des versions
contrôle de version

Pour plus d’informations sur l’utilisation d’un manifeste, consultez 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 commande git pull pour mettre à jour le registre vcpkg vers le dernier commit.
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 fichier vcpkg.json.
- 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 :
- Exécutez à nouveau la commande vcpkg install dans votre terminal ou invite de commandes.

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

Un conflit de schéma de version se produit lorsque la version spécifiée dans le fichier vcpkg.json pour une dépendance utilise un schéma de contrôle de version différent de celui utilisé dans la version de base 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 de version>= déclarée 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 :
- Inspectez la base de données de version dans le référentiel vcpkg sous versions/b-/boost-regex.json pour rechercher une version de boost-regex qui utilise le même schéma de contrôle de version que la base de référence.
- Mettez à jour la contrainte version>= dans votre vcpkg.json vers une version qui utilise un schéma compatible.
Remplacez par 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 pour inclure une section de remplacements spécifiant la version souhaitée :
```
{
  "dependencies": [
    { "name": "boost-regex" }
  ],
  "overrides": [
    { "name": "boost-regex", "version": "1.75.0" }
  ]
}
```

Cause : Historique des commits inadéquat dans un clone superficiel

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 extrait. 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’utilisation d’un vcpkg.json avec une ligne de base spécifique, telle que :

{
  "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 superficiels par défaut)
- GitHub Actions utilise souvent des clones peu profonds par défaut. 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 un encombrement inattendu ou des fonctionnalités inattendues dans votre build final.

Scénario

Vous avez une dépendance sur la bibliothèque Y, qui dépend de la bibliothèque X. La bibliothèque X dispose de 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 que X soit installé sans ses fonctionnalités par défaut en raison du paramètre "default-features": false. Toutefois, X est toujours installé avec la fonctionnalité par défaut foo.

Raison

La propriété default-features n’est considérée qu’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 paramètre "default-features": false à la dépendance transitive X, ce qui entraîne l’installation de X avec ses fonctionnalités par défaut.

Résolution

Pour vous assurer que les dépendances transitives telles que 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 votre 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 que X est installé sans ses fonctionnalités par défaut, car maintenant X est 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 concept de fonctionnalités par défaut article.

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

Si votre problème n’est pas répertorié ici, visitez notre dépôt pour enregistrer un nouveau problème.

Partage via