Partage via

Informations de référence sur le contrôle de version

  • Article

Le contrôle de version vous permet de contrôler de manière déterministe les révisions précises des dépendances utilisées par votre projet à partir de votre fichier manifeste. Le contrôle de version n’est disponible que pour mode manifeste utilisateurs.

Pour plus d’informations sur l’algorithme de contrôle de version vcpkg et les concepts généraux, consultez Concepts de gestion de version.

Pour obtenir un exemple de contexte, consultez notre guide pour prise en main du contrôle de version.

Schémas de version

Les ports dans vcpkg doivent tenter de suivre les conventions de contrôle de version utilisées par les auteurs du package. Pour cette raison, lors de la déclaration de la version d’un package, le schéma approprié doit être utilisé.

Chaque schéma de contrôle de version définit ses propres règles sur ce qui est une chaîne de version valide et, plus important encore, les règles pour trier les versions à l’aide du même schéma.

Les schémas de contrôle de version compris par vcpkg sont les suivants :

Propriété manifeste Schéma de contrôle de version
version Pour les versions numériques séparées par des points
version-semver Pour les versions conformes à SemVer
version-date Pour les dates au format YYYY-MM-DD
version-string Pour les chaînes arbitraires

Un manifeste ne doit contenir qu’une seule déclaration de version.

Note

Par conception, vcpkg ne compare pas les versions qui utilisent différents schémas. Par exemple, un package qui a un version-string: 7.1.3 ne peut pas être comparé au même package à l’aide de version: 7.1.4, même si la conversion semble évidente.

version

Accepte les chaînes de version qui suivent un schéma détendu, séparé par des points, semver-like.

La version est composée logiquement de sections numériques séparées par des points (.). Chaque section doit contenir un nombre positif entier sans zéros non significatifs.

Le modèle d’expression régulière pour ce schéma de contrôle de version est le suivant : (0|[1-9]\d*)(\.(0|[1-9]\d*))*

comportement de tri: lors de la comparaison de deux versions, chaque section est comparée de gauche à droite par leur valeur numérique, jusqu’à ce que la première différence soit trouvée. Une version avec le plus petit ensemble de sections est prioritaire sur une autre avec un plus grand ensemble de sections, étant donné que toutes leurs sections précédentes comparent de façon égale.

Exemple:

0 < 0.1 < 0.1.0 < 1 < 1.0.0 < 1.0.1 < 1.1< 2.0.0

version-semver

Accepte les chaînes de version qui suivent les conventions de gestion de version sémantique, comme décrit dans la spécification de contrôle de version sémantique .

comportement de tri: les chaînes sont triées en suivant les règles décrites dans la spécification de contrôle de version sémantique.

Exemple:

1.0.0-1 < 1.0.0-alpha < 1.0.0-beta < 1.0.0 < 1.0.1 < 1.1.0

version-date

Accepte les chaînes de version qui peuvent être analysées à une date suivant le format ISO-8601 YYYY-MM-DD. Les identificateurs d’ambiguïté sont autorisés sous la forme de nombres entiers séparés par des points, positifs, sans zéros non significatifs.

Il s’agit du schéma de contrôle de version recommandé pour les bibliothèques « Live at HEAD » qui n’ont pas de versions de version établies.

Le modèle d’expression régulière pour ce schéma de contrôle de version est le suivant : \d{4}-\d{2}-\d{2}(\.(0|[1-9]\d*))*

comportement de tri: les chaînes sont triées en premier par leur partie de date, puis par comparaison numérique de leurs identificateurs d’ambiguïté. Les identificateurs d’ambiguïté suivent les règles du schéma détendu (version).

Exemples : 2021-01-01<2021-01-01.1<2021-02-01.1.2<2021-02-01.1.3<2021-02-01

version-string

Pour les packages utilisant des chaînes de version qui ne correspondent à aucun des autres schémas, il accepte la plupart des chaînes arbitraires. La # utilisée pour indiquer que les versions de port ne sont pas autorisées.

comportement de tri: aucun tri n’est tenté sur la chaîne de version elle-même. Toutefois, si les chaînes correspondent exactement, leurs versions de port peuvent être comparées et triées.

Exemples:

  • apple <> orange <> orange.2 <> orange2
  • watermelon#0< watermelon#1

port-version

Les versions de port effectuent le suivi des modifications dans les fichiers d’empaquetage (vcpkg.json, portfile.cmake, etc.) sans aucune modification apportée à la version de la bibliothèque en amont.

Une version de port est une valeur entière non négative.

Les règles pour les versions de port sont les suivantes :

  • Commencez à 0 pour la version d’origine du port,
  • augmentez de 1 chaque fois qu’une modification spécifique à vcpkg est apportée au port qui n’augmente pas la version du package,
  • et réinitialisation à 0 chaque fois que la version du package est mise à jour.

Note

vcpkg suit le format de texte <version>#<port version>. Par exemple, 1.2.0#2 signifie la version 1.2.0 version du port 2. Si la version du port est 0 le suffixe #0 est omis (par exemple, 1.2.0 implique la version 1.2.0 version du port 0).

comportement de tri: si deux versions comparent de manière égale, leurs versions de port sont comparées par leur valeur numérique, les versions de port inférieures sont prioritaires.

Exemples:

  • 1.2.0 < 1.2.0#1 < 1.2.0#2 < 1.2.0#10
  • 2021-01-01#20 < 2021-01-01.1
  • windows#7 < windows#8

Contraintes de version

Lignes

Les bases de référence définissent un étage de version global pour les versions qui seront prises en compte (sauf indication ailleurs, la version associée à cette base de référence sera utilisée). Cela permet aux manifestes de niveau supérieur de conserver l’intégralité du graphique des dépendances up-to-date sans avoir à spécifier individuellement des contraintes de "version>=" directes.

Chaque registre configuré a une base de référence associée. Pour les manifestes qui ne configurent pas de registres, le champ "builtin-baseline" définit la base de référence pour le registre intégré. Si un manifeste ne configure pas de registres et n’a pas de "builtin-baseline", l’installation fonctionne en fonction de l’algorithme de mode Classique et ignore toutes les informations de contrôle de version.

Les bases de référence, comme d’autres paramètres de Registre, sont ignorées des ports consommés en tant que dépendance. Si une version minimale est requise pendant la résolution de version transitive, le port doit utiliser "version>=".

Exemple

{
  "name": "project",
  "version": "1.0.0",
  "dependencies": ["zlib", "fmt"],
  "builtin-baseline":"9fd3bd594f41afb8747e20f6ac9619f26f333cbe"
}

Pour ajouter une "builtin-baseline"initiale, utilisez vcpkg x-update-baseline --add-initial-baseline. Pour mettre à jour les bases de référence dans un manifeste, utilisez vcpkg x-update-baseline.

version>=

Exprime une exigence de version minimale, version>= déclarations placent une limite inférieure sur les versions qui peuvent être utilisées pour satisfaire une dépendance.

Note

vcpkg sélectionne la version la plus basse qui correspond à toutes les contraintes. Par conséquent, une contrainte inférieure à celle-ci n’est pas requise.

Exemple:

{
  "name": "project",
  "version-semver": "1.0.0",
  "dependencies": [
    { "name": "zlib", "version>=": "1.2.11#9" },
    { "name": "fmt", "version>=": "7.1.3#1" }
  ],
  "builtin-baseline":"3426db05b996481ca31e95fff3734cf23e0f51bc"
}

Dans le cadre d’une déclaration de contrainte de version, une version de port peut être spécifiée en ajoutant le suffixe #<port-version>, dans l’exemple précédent 1.2.11#9 fait référence à la version 1.2.11 version de port 9.

overrides

La déclaration d’un remplacement force vcpkg à ignorer toutes les autres contraintes de version et à utiliser la version spécifiée dans le remplacement. Cela est utile pour épingler des versions exactes et pour résoudre les conflits de version.

Les remplacements sont déclarés sous la forme d’un tableau de déclarations de version de package.

Pour qu’un remplacement prenne effet, le package substitué doit faire partie du graphique de dépendances. Cela signifie qu’une dépendance doit être déclarée par le manifeste de niveau supérieur ou faire partie d’une dépendance transitive.

Une seule substitution peut être déclarée pour un nom donné.

{
  "name": "project",
  "version-semver": "1.0.0",
  "dependencies": [
    "curl",
    { "name": "zlib", "version>=": "1.2.11#9" },
    "fmt"
  ],
  "builtin-baseline":"3426db05b996481ca31e95fff3734cf23e0f51bc",
  "overrides": [
    { "name": "fmt", "version": "6.0.0" },
    { "name": "openssl", "version": "1.1.1h#3" }
  ]
}