Informations de référence sur les registres

Vue d’ensemble

Cet article décrit les détails de l’implémentation pour chaque type de registre. Plus précisément, ce fichier concerne la disposition recommandée pour chaque type de registre et le contenu attendu de leur base de données versions respectives.

Registres Git

Disposition des fichiers de référence dans les registres Git

Champs de niveau supérieur

L’objet de niveau supérieur d’un fichier baseine.json est un dictionnaire, chaque clé de ce dictionnaire est une nommée ligne de base. En raison des détails d’implémentation des registres Git, il est nécessaire qu’un nommé base de référence avec le nom « par défaut » existe et qu’il contient un mappage de tous les ports du Registre à leur version de base de référence.

BaselineObject

L’objet de base est un dictionnaire, avec chaque clé correspondant à un nom de port dans le Registre et sa valeur étant la dernière version du port.

BaselineVersionObject

Exemple de fichier baseline.json dans un registre Git

Dans un registre contenant un seul port nommé foo à la version 1.0.0#1, le contenu du fichier baseline.json doit être :

{
  "default": {
    "foo": { 
      "baseline": "1.0.0", 
      "port-version": 1
    }
  }
}

Disposition des fichiers de version dans les registres Git

Le répertoire versions contient toutes les informations sur les versions de packages contenues dans le Registre, ainsi que la méthode permettant de récupérer ces versions à partir de l’historique du référentiel.

Champs de niveau supérieur

VersionObject

Exemple de fichier de versions de Registre Git

{
  "versions": [
    {
      "git-tree": "963060040c3ca463d17136e39c7317efb15eb6a5",
      "version": "1.2.0",
      "port-version": 0
    },
    {
      "git-tree": "548c90710d59c174aa9ab10a24deb69f1d75ff8f",
      "version": "1.1.0",
      "port-version": 0
    },
    {
      "git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e",
      "version": "1.0.0",
      "port-version": 0
    }
  ]
}

Obtention d’une git-tree SHA

vcpkg utilise les fonctionnalités de Git pour récupérer des versions spécifiques d’un port contenu dans son historique de validation. La méthode utilisée consiste à récupérer l’objet git-tree à partir du référentiel, comme spécifié dans le fichier de versions d’un port.

Chaque répertoire de ports d’un registre Git a une SHA unique associée à celle-ci (appelée git-tree dans les fichiers de versions). Le sha est calculé à l’aide du contenu du répertoire ; chaque fois qu’une modification est validée dans le référentiel qui modifie un répertoire, sa sha est recalculée.

Git vous permet de récupérer le contenu d’un répertoire donné à tout moment de son historique, à condition que vous connaissiez leur SHA spécifique. En utilisant cette fonctionnalité, vcpkg peut indexer des versions de port spécifiques avec leur SHA (git-tree).

Pour obtenir la sha d’un répertoire de port à n’importe quelle révision donnée, la commande Git suivante peut être utilisée :

git -C <path/to/ports> ls-tree --format='%(objectname)' <commit sha> -- <portname>

Exemple:

git -C %VCPKG_ROOT%/ports ls-tree --format='%(objectname)' HEAD -- curl
6ef1763f3cbe570d6378632c9b5793479c37fb07

La commande retourne la sha du répertoire contenant le port curl à la révision actuelle (HEAD).

Il est possible d’afficher le contenu du git-tree à l’aide de la commande git show <git-tree>:

git show 6ef1763f3cbe570d6378632c9b5793479c37fb07
tree 6ef1763f3cbe570d6378632c9b5793479c37fb07

0005_remove_imp_suffix.patch
0020-fix-pc-file.patch
0022-deduplicate-libs.patch
cmake-config.patch
cmake-project-include.cmake
dependencies.patch
export-components.patch
portfile.cmake
redact-input-vars.diff
usage
vcpkg-cmake-wrapper.cmake
vcpkg.json

Ou le contenu d’un fichier spécifique avec git show <git-tree>:<file>:

git show 6ef1763f3cbe570d6378632c9b5793479c37fb07:usage
curl is compatible with built-in CMake targets:

    find_package(CURL REQUIRED)
    target_link_libraries(main PRIVATE CURL::libcurl)

La gestion des fichiers de base de données à jour à l’aide de ces commandes Git dans un processus manuel peut être une tâche difficile. Pour cette raison, nous vous recommandons d’utiliser la commande x-add-version, qui automatise le processus tant que le référentiel suit la structure de Registre recommandée. Consultez le tutoriel : Publier des packages dans un registre vcpkg privé à l’aide de Git article pour obtenir un exemple de publication d’un port dans un registre Git.

Registres de système de fichiers

Disposition des fichiers de référence dans les registres de système de fichiers

Champs de niveau supérieur

L’objet de niveau supérieur d’un fichier baseine.json est un dictionnaire, chaque clé de ce dictionnaire est une nommée ligne de base. Les bases de référence doivent contenir des mappages de tous les ports du Registre à leur version de référence.

BaselineObject

L’objet de base est un dictionnaire, avec chaque clé correspondant à un nom de port dans le Registre et sa valeur étant la dernière version du port.

BaselineVersionObject

La disposition du fichier de base dans un registre de système de fichiers est la même que pour registres Git. La seule différence étant que les systèmes de fichiers ne nécessitent pas de base de default.

Exemple de fichier baseline.json dans un registre Git

{
  "2024-12-01": {
    "foo": {
      "baseline": "1.0.0",
      "port-version": 1
    }
  }
}

Disposition des fichiers de version dans les registres Git

Le répertoire versions contient toutes les informations sur les versions de packages contenues dans le Registre, ainsi que la méthode permettant de récupérer ces versions à partir d’un emplacement de système de fichiers.

champs de niveau supérieur

VersionObject

Lorsque vous spécifiez la path d’un registre, le caractère $ peut être utilisé pour référencer la racine du Registre. Sinon, les chemins absolus peuvent être utilisés à la place.

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

Étapes suivantes

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

• Lire la documentation conceptuelle des registres
• créer votre propre registre git
• Installer des packages à partir d’un registre personnalisé