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

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 les utilisateurs en mode manifeste.

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

Pour obtenir un exemple de contexte, consultez notre guide de 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 :

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

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 regex 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 gestion 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 YYYY-MM-DDISO-8601 . 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 regex 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. Ce # qui est utilisé pour désigner les versions de port est interdit.

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.cmakeetc.) sans aucune modification apportée à la version de la bibliothèque 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.

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 de base

Les bases de référence définissent un étage de version global pour les versions qui seront prises en compte. Cela permet aux manifestes de niveau supérieur de conserver l’intégralité du graphique des dépendances à jour sans avoir à spécifier individuellement des contraintes directes "version>=" .

Chaque registre configuré a une base de référence associée. Pour les manifestes qui ne configurent pas de registres, le "builtin-baseline" champ 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"registre, 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 un initial "builtin-baseline", 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>= les déclarations placent une limite inférieure sur les versions qui peuvent être utilisées pour satisfaire une dépendance.

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 1.2.11#9 précédent fait référence à la version du port de version 1.2.119.

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 de l’graphe des 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.

{
  "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" }
  ]
}