Partager via

Concepts des registres

  • Article

Aperçu

vcpkg héberge une sélection de bibliothèques empaquetées dans des ports à https://github.com/Microsoft/vcpkg. Cette collection de ports est appelée registre curationné. Toutefois, vcpkg n’est pas limité au registre organisé. Les utilisateurs peuvent étendre la sélection de ports en créant des registres personnalisés.

Un registre est une collection de ports et de fichiers d’assistance organisés dans une structure spécifique. En suivant la structure du registre, les ports contenus dans un registre peuvent être installés avec les mêmes fonctionnalités de contrôle de version (,) et de mise en cache binaire (,) proposées aux ports dans le registre organisé.

Il existe actuellement trois types de registres :

vcpkg peut être invité à prendre en compte les ports disponibles dans les registres personnalisés à l’aide d’un fichier vcpkg-configuration.json. Consultez le didacticiel : Installer une dépendance à partir d’un registre basé sur Git article pour obtenir un didacticiel sur l’utilisation de registres personnalisés dans vos projets.

Structure du Registre

Pour que vcpkg s’interface avec un registre, il doit être conforme à la structure suivante :

  • Un répertoire nommé ports contient la collection de ports, chaque sous-répertoire contenant un port spécifique correspondant au nom du sous-répertoire. Par exemple, les fichiers du port foo sont situés dans ports/foo.
  • Un répertoire nommé versions contient les fichiers qui composent la base de données versions.

Exemple : structure de Registre

ports/
  foo/
    portfile.cmake
    vcpkg.json
versions/
  f-/
    foo.json
  baseline.json

Base de données des versions

Tous les registres contiennent un répertoire versions à la racine du registre qui contient la base de données des versions .

Il existe deux composants dans la base de données des versions :

  • Fichier de référence
  • Fichiers de version

Le fichier de base est un fichier JSON nommé baseline.json situé à la racine du répertoire versions.

Les fichiers de versions sont des fichiers JSON portant les mêmes noms que les ports disponibles. Ils doivent exister à versions/<prefix>/<port name>.json, où <prefix> est la première lettre du nom du port suivi d’un trait d’union. Par exemple, le fichier de versions pour le port foo doit être à versions/f-/foo.json.

L’objectif du fichier de versions est double :

  • Répertorier toutes les versions disponibles de chaque port
  • Pointez sur les emplacements de récupération de chaque version.

Le format du fichier de version dépend du type du registre.

Fichier de référence

Tous les registres, quel que soit leur type, doivent contenir un fichier nommé baseline.json situé à versions/baseline.json.

L’objectif du fichier de base est de décrire l’ensemble des versions considérées comme les plus récentes pour tous les ports du Registre. Il est prévu que ce fichier soit mis à jour chaque fois qu’une nouvelle version d’un port est ajoutée au Registre.

Le fichier est un fichier JSON composé d’un objet unique dont les propriétés sont nommées objets de référence. Les propriétés de chaque objet de référence sont des noms de port, dont les valeurs sont des entrées de version. L’article relatif aux informations de référence sur les registres décrit plus en détail la disposition des fichiers de ligne de base.

Chaque entrée de version de référence est un objet avec les propriétés suivantes :

  • baseline : la valeur est la version du port correspondant à son fichier vcpkg.json.
  • port-version : la valeur est la port-version correspondant à son fichier vcpkg.json.

Exemple de fichier de référence

{
  "default": {
    "foo": { "baseline": "1.0.0", "port-version": 0 },
    "bar": { "baseline": "2024-08-01", "port-version": 1 },
    "baz": { "baseline": "vista-xp", "port-version": 0 }
  }
}

Consultez la documentation de référence pour :

  • Disposition des fichiers de ligne de base pour les registres Git
  • Disposition des fichiers de référence pour les registres de système de fichiers

Fichiers de versions

Chaque port du Registre a un fichier de versions correspondant. Les fichiers de versions sont stockés à versions/<prefix>/<port name>.json, où <prefix> est la première lettre du nom de port suivi d’un trait d’union. Par exemple, le fichier de versions pour le port foo se trouve à versions/f-/foo.json.

L’objectif du fichier de versions est double :

  • Répertorier toutes les versions disponibles de chaque port
  • Pointez vers les emplacements de récupération de chacune de ces versions

La disposition du fichier de versions est un objet contenant un tableau "versions", chaque entrée de ce tableau étant un objet de version. Un objet de version doit contenir les propriétés suivantes :

  • Propriété de version : la clé et la valeur de la propriété doivent correspondre à celles utilisées par le port dans son fichier vcpkg.json. La clé doit être l’une des version, version-semver, version-dateou version-string; la valeur doit être la version telle qu’elle apparaît dans le fichier manifeste du port (vcpkg.json).
  • port-version: la valeur est la port-version du port telle qu’elle apparaît dans le fichier vcpkg.json du port.
  • git-tree: (uniquement sur les registres Git) la valeur est l’arborescence Git SHA correspondant au répertoire du port. Il s’agit d’un SHA calculé en hachant le contenu du répertoire du port ; Ce SHA git-tree peut être utilisé par Git pour récupérer le contenu du port correspondant à l’arborescence git fournie. Cela permet à vcpkg de récupérer les anciennes versions des ports à partir de l’historique Git des registres. Lisez les registres git section pour savoir comment obtenir cette valeur pour une version de port donnée.
  • path: (uniquement sur les registres de système de fichiers) la valeur est le chemin complet d’un répertoire contenant les fichiers de port pour la version spécifique.

Exemple de fichier de version du registre du système de fichiers

{
  "versions": [
    {
      "path": "$/ports/foo/1.2.0",
      "version": "1.2.0",
      "port-version": 0
    },
    {
      "path": "$/ports/foo/1.1.0",
      "version": "1.1.0",
      "port-version": 0
    },
    {
      "path": "$/ports/foo/1.0.0",
      "version": "1.0.0",
      "port-version": 0
    }
  ]
}

Consultez la documentation de référence pour :

  • Disposition des fichiers de versions pour les registres Git
  • Disposition des fichiers de versions pour les registres de système de fichiers

Registre intégré

Le registre intégré est un type spécial de registre. Il s’agit du registre par défaut utilisé en mode classique . En mode manifeste, lorsqu’un registre par défaut n’est pas spécifié, vcpkg utilise implicitement le registre intégré.

Le registre intégré fait référence à la copie locale du registre organisé créée lorsque vous git clone le référentiel vcpkg à partir de https://github.com/Microsoft/vcpkg. Certaines opérations s’attendent à ce que la variable d’environnementVCPKG_ROOT pointe vers un registre intégré.

Si vcpkg est acquis via le programme d’installation « one liner » ou Visual Studio, le registre intégré devient équivalent à un registre Git pointant vers le référentiel https://github.com/Microsoft/vcpkg.

Registres Git

Un registre Git est un référentiel qui suit la structure du Registre et tire parti des fonctionnalités de Git pour fournir un contrôle de version pour les ports du Registre. Le registre organisé à https://github.com/Microsoft/vcpkg est une implémentation d’un registre Git.

Les registres Git peuvent être hébergés dans n’importe quel fournisseur de référentiel Git, ce qui vous permet d’utiliser votre service d’hébergement Git choisi pour contrôler l’accès à votre registre personnalisé tout en facilitant le partage de votre registre.

Les registres Git sont la méthode recommandée pour implémenter un registre personnalisé. Étant donné que le mécanisme de contrôle de version est le même que celui utilisé par le registre organisé, les registres Git peuvent utiliser les x-add-version pour gérer vos fichiers de base de données de version.

Consultez la référence registres pour obtenir des détails sur l’implémentation des registres Git.

Ajout d’une nouvelle version à un registre Git

La commande x-add-version peut être utilisée pour ajouter un nouveau port ou une nouvelle version au Registre. Lorsque vous ajoutez des versions à l’aide de cette commande, il existe quelques éléments à garder à l’esprit :

Important

Lors de l’ajout d’une nouvelle version, n’oubliez pas de mettre à jour la version déclarée du port vers une version non déjà publiée, afin d’éviter de réécrire l’historique des versions.

Lorsque vous apportez des modifications à un port, la première étape doit être d’augmenter sa version dans le fichier vcpkg.json. Si vos modifications incluent une mise à jour de la version en amont du paquet , n'oubliez pas de mettre l'port-version sur 0; sinon, n'oubliez pas d'augmenter le port-version de un.

La commande x-add-version nécessite que toutes vos modifications de port soient validées dans le référentiel avant de mettre à jour la base de données de version.

Exemple : ajout d’une nouvelle version de port à un registre Git

git add ports/foo/.
git commit -m "Temporary commit"
vcpkg x-add-version --x-builtin-ports-root=./ports --x-builtin-registry-versions-dir=./versions foo
added version 1.0.0#1 to path/to/registry/versions/f-/foo.json
added version 1.0.0#1 to path/to/registry/versions/baseline.json

Les options de redirection --x-builtin-ports-root et --x-builtin-registry-versions-dir doivent pointer respectivement vers les répertoires ports et versions de votre Registre.

Une fois, la commande x-add-version s’exécute correctement, modifiez la dernière validation pour inclure les modifications apportées au fichier de versions.

git commit --amend -m "Update foo to new version"

Registres de système de fichiers

Les registres de système de fichiers sont une implémentation d’un registre qui vit sur un système de fichiers. Ils suivent la structure de Registre commune, mais n’utilisent pas Git pour offrir des fonctionnalités de contrôle de version. Au lieu de cela, ils utilisent une forme primitive de contrôle de version à l’aide d’un chemin distinct pour chaque version de ses ports.

Ce type de registre convient pour être un terrain de test pour vos ports ou pour fournir une alternative à un registre dans un système de contrôle de version non Git. Les registres de système de fichiers ne sont pas recommandés pour la grande collection de ports et aucun outil n’est fourni pour manipuler les fichiers de base de données de version pour ce type de registre.

Consultez la référence des registres pour plus d’informations sur l’implémentation d’un registre de système de fichiers.

Utiliser des registres

Pour utiliser un registre personnalisé dans votre projet, vous devez créer un fichier de configuration (vcpkg-configuration.json) en regard du fichier manifeste de votre projet (vcpkg.json).

Registre par défaut

Lors de la résolution des noms de ports, le registre par défaut fonctionne comme la solution de secours lorsqu’un nom de port ne correspond à aucun des modèles de package déclarés par d’autres registres dans le tableau registries.

Comme commodité pour les utilisateurs qui n’interagissent pas avec des registres personnalisés, vcpkg ajoute implicitement le registre intégré comme registre par défaut. Pour modifier ce comportement, le registre par défaut peut être défini sur n’importe quel registre ou désactivé complètement à l’aide du Propriété default-registry.

Exemple : définir un registre personnalisé comme valeur par défaut

vcpkg-configuration.json

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/Microsoft/vcpkg",
    "baseline": "84a143e4caf6b70db57f28d04c41df4a85c480fa"
  }
}

Exemple : Désactiver le registre par défaut

vcpkg-configuration.json

{
  "default-registry": null
}

Tableau de registres

Pour étendre la sélection de ports disponibles pour l’installation avec vcpkg, vous pouvez spécifier des registres supplémentaires à l’aide du tableau registries.

Exemple : Ajouter des registres personnalisés à la configuration

Remarque

Selon le type de Registre, vous devrez peut-être fournir différentes informations dans le tableau registries. Consultez la vcpkg-configurtion.json Référence pour savoir quelles propriétés sont requises pour chaque type de registre.

vcpkg-configuration.json

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/Microsoft/vcpkg",
    "baseline": "84a143e4caf6b70db57f28d04c41df4a85c480fa"
  },
  "registries": [
    {
      "kind": "git",
      "repository": "https://my.privateregistry.git",
      "baseline": "caf6b70db5784a143e4f28d05c480fa4c41df4a8",
      "packages": [ "foo" ]
    },
    {
      "kind": "filesystem",
      "path": "C:/path/to/registry",
      "baseline": "baseline1",
      "packages": [ "bar" ]
    }
  ]
}

Ne réécrire pas l’historique des versions

Une fois qu’une version a été publiée dans les fichiers de versions, ne modifiez pas ses git-tree associées dans un registre git ou un répertoire dans un registre de système de fichiers.

L’un des principes de conception de vcpkg est que les versions des dépendances installées ne changent pas sans intervention de l’utilisateur. La réécriture de l’historique des fichiers de versions en modifiant une entrée git-tree enfreint ce principe.

Si la version existante présente des problèmes, préférez créer une nouvelle port-version.

Ne supprimez pas les fichiers de versions

Remarque

Cette section s’applique uniquement aux registres Git

Lorsque vous supprimez un port de votre registre, supprimez son contenu du répertoire des ports et son entrée dans le fichier de référence. Mais ne supprimez pas son fichier de versions associé.

Même si un port n’existe plus dans le Registre, tant que le fichier de versions reste, les utilisateurs du port peuvent installer les anciennes versions à l’aide de version overrides.

Étapes suivantes

Voici quelques tâches à effectuer à l’étape suivante :