Partager via

Création de registres

  • Article

Pour plus d’informations sur la consommation de registres, consultez Utilisation de registres.

Vue d’ensemble

Les registres sont des collections de ports et de leurs versions. Il existe deux choix majeurs d’implémentation pour les registres, si vous souhaitez créer vos propres registres : registres git et registres de système de fichiers.

Les registres Git sont des référentiels Git simples et peuvent être partagés publiquement ou en privé via des mécanismes normaux pour les dépôts Git. Le référentiel vcpkg, par exemple, est un registre git.

Les registres de système de fichiers sont conçus comme plus d’un terrain de test. Étant donné qu’ils vivent littéralement sur votre système de fichiers, la seule façon de les partager est via des répertoires partagés. Toutefois, les registres de système de fichiers peuvent être utiles pour représenter les registres détenus dans les systèmes de contrôle de version non git, en supposant qu’il existe un moyen d’obtenir le registre sur le disque.

Nous nous attendons à ce que l’ensemble des types de Registre augmente au fil du temps ; si vous souhaitez prendre en charge les registres intégrés dans votre système de contrôle de version public favori, n’hésitez pas à ouvrir une demande de tirage.

La structure de base d’un registre est la suivante :

  • Ensemble de versions considérées comme « les plus récentes » à certains moments de l’historique, appelées « base de référence ».
  • Ensemble de toutes les versions de tous les ports et où trouver chacun d’eux dans le Registre.

Registres Git

À mesure que vous suivez cette documentation, il peut être utile d’avoir un exemple de travail à consulter. Nous en avons écrit un et nous l’avons mis ici :

Microsoft/vcpkg-docs : registre vcpkg.

Tous les registres Git doivent avoir un versions/baseline.json fichier. Ce fichier contient l’ensemble de « dernières versions » à une certaine validation. Il est disposé en tant qu’objet de niveau supérieur contenant uniquement le "default" champ. Ce champ doit contenir un nom de port de mappage d’objets vers la version actuellement la plus récente.

Voici un exemple de baseline.json valide :

{
  "default": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  }
}

Le versions répertoire contient toutes les informations sur les versions des packages contenus dans le Registre, ainsi que l’emplacement où ces versions sont stockées. Le reste du registre agit simplement comme magasin de stockage, en ce qui concerne vcpkg : seules les choses à l’intérieur du versions répertoire seront utilisées pour diriger la façon dont votre registre est vu par vcpkg.

Chaque port d’un registre doit exister dans le répertoire des versions comme <first letter of port>-/<name of port>.json; en d’autres termes, les informations relatives au kitten port se trouvent dans versions/k-/kitten.json. Il doit s’agir d’un objet de niveau supérieur avec un seul champ : "versions". Ce champ doit contenir un tableau d’objets de version :

  • Version du port en question ; doit être exactement identique au vcpkg.json fichier, y compris les champs de version et "port-version".
  • Le "git-tree" champ, qui est une arborescence git ; en d’autres termes, ce que vous obtenez lorsque vous écrivez git rev-parse COMMIT-ID:path/to/port.

Le champ de version pour les ports avec des fichiers dépréciés CONTROL est "version-string".

Avertissement

Une partie très importante des registres est que les versions ne doivent jamais être modifiées. La mise à jour vers une référence ultérieure ne doit jamais supprimer ou modifier une version existante. Il doit toujours être sûr de mettre à jour un registre.

Voici un exemple de base de données de version valide pour un kitten port avec une version :

{
  "versions": [
    {
      "version": "2.6.2",
      "port-version": 0,
      "git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e"
    }
  ]
}

En général, il n’est pas important de placer des répertoires de ports. Toutefois, l’idiome dans vcpkg consiste à suivre ce que fait le registre vcpkg intégré : votre kitten port doit être placé dans ports/kitten.

Avertissement

Une autre chose à garder à l’esprit est que lorsque vous mettez à jour un registre, toutes les versions précédentes doivent également être accessibles. Étant donné que votre utilisateur définit sa ligne de base sur un ID de validation, cet ID de validation doit toujours exister et être accessible à partir de votre validation HEAD, c’est-à-dire ce qui est réellement récupéré. Cela signifie que votre validation HEAD doit être un enfant de toutes les validations HEAD précédentes.

Registres intégrés

Les registres intégrés sont traités comme des registres Git spéciaux. Au lieu d’extraire à partir d’une URL distante, les registres intégrés consultent le $VCPKG_ROOT/.git répertoire du clone vcpkg. Ils utilisent le répertoire actuellement extrait $VCPKG_ROOT/versions comme source pour les informations de contrôle de version.

Ajout d’une nouvelle version

Il existe des astuces git impliquées dans la création d’une nouvelle version d’un port. La première chose à faire est d’apporter des modifications, de mettre à jour le "port-version" champ de version standard au fur et à mesure que vous avez besoin, puis de tester avec overlay-ports:

vcpkg install kitten --overlay-ports=ports/kitten.

Une fois que vous avez terminé vos tests, vous devez vous assurer que le répertoire tel qu’il se trouve sous le purview de Git. Pour ce faire, vous allez créer une validation temporaire :

> git add ports/kitten
> git commit -m 'temporary commit'

Ensuite, obtenez l’ID d’arborescence Git du répertoire :

> git rev-parse HEAD:ports/kitten
73ad3c823ef701c37421b450a34271d6beaf7b07

Ensuite, vous pouvez ajouter cette version à la base de données des versions. En haut de votre versions/k-/kitten.json, vous pouvez ajouter (en supposant que vous ajoutez la version 2.6.3#0) :

{
  "versions": [
    {
      "version": "2.6.3",
      "port-version": 0,
      "git-tree": "73ad3c823ef701c37421b450a34271d6beaf7b07"
    },
    {
      "version": "2.6.2",
      "port-version": 0,
      "git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e"
    }
  ]
}

Ensuite, vous souhaiterez également modifier votre versions/baseline.json nouvelle version :

{
  "default": {
    "kitten": {
      "baseline": "2.6.3",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  }
}

et modifiez votre validation actuelle :

> git commit --amend

puis partagez !!

Registres de système de fichiers

À mesure que vous suivez cette documentation, il peut être utile d’avoir un exemple de travail à consulter. Nous en avons écrit un et nous l’avons mis ici :

Exemple de registre de système de fichiers.

Tous les registres de système de fichiers doivent avoir un versions/baseline.json fichier. Ce fichier contient l’ensemble de « dernières versions » pour une certaine version du Registre. Il est disposé en tant qu’objet de niveau supérieur contenant un mappage du nom de version aux « objets de base », qui mappent les noms de port à la version considérée comme « la plus récente » pour cette version du Registre.

Les registres de système de fichiers doivent décider d’un schéma de contrôle de version. Contrairement aux registres Git, qui ont le schéma de contrôle de version implicite des références, les registres de système de fichiers ne peuvent pas s’appuyer sur le système de contrôle de version ici. Une option possible consiste à faire une version quotidienne et à avoir vos « versions » comme dates.

Avertissement

Une base de référence ne doit pas être modifiée une fois publiée. Si vous souhaitez modifier ou mettre à jour des versions, vous devez créer une base de référence dans le baseline.json fichier.

Voici un exemple d’un registre valide baseline.jsonqui a décidé des dates pour leurs versions :

{
  "2021-04-16": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  },
  "2021-04-15": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 1
    }
  }
}

Le versions répertoire contient toutes les informations sur les versions des packages contenus dans le Registre, ainsi que l’emplacement où ces versions sont stockées. Le reste du registre agit simplement comme magasin de stockage, en ce qui concerne vcpkg : seules les choses à l’intérieur du versions répertoire seront utilisées pour diriger la façon dont votre registre est vu par vcpkg.

Chaque port d’un registre doit exister dans le répertoire des versions comme <first letter of port>-/<name of port>.json; en d’autres termes, les informations relatives au kitten port se trouvent dans versions/k-/kitten.json. Il doit s’agir d’un objet de niveau supérieur avec un seul champ : "versions". Ce champ doit contenir un tableau d’objets de version :

  • Version du port en question ; doit être exactement identique au vcpkg.json fichier, y compris les champs de version et "port-version".
  • Champ "path" : répertoire relatif, rooté à la base du registre (en d’autres termes, répertoire versions où se trouve le répertoire), au répertoire de port. Il devrait ressembler à "$/path/to/port/dir"

Le champ de version pour les ports avec des fichiers dépréciés CONTROL est "version-string".

En général, il n’est pas important de placer des répertoires de ports. Toutefois, l’idiome dans vcpkg est de suivre un peu près ce que fait le registre vcpkg intégré : votre kitten port à la version x.y.z doit être placé ports/kitten/x.y.z, avec les versions de port ajoutées comme vous le voyez (bien que ce # n’est pas un bon caractère à utiliser pour les noms de fichiers, peut-être utiliser _).

Avertissement

Une partie très importante des registres est que les versions ne doivent jamais être modifiées. Il ne faut jamais supprimer ou modifier une version existante. Vos modifications apportées à votre registre ne doivent pas changer de comportement pour les utilisateurs en aval.

Voici un exemple de base de données de version valide pour un kitten port avec une version :

{
  "versions": [
    {
      "version": "2.6.2",
      "port-version": 0,
      "path": "$/ports/kitten/2.6.2_0"
    }
  ]
}

Ajouter une nouvelle version

Contrairement aux registres Git, l’ajout d’une nouvelle version à un registre de système de fichiers implique principalement une grande partie de la copie. La première chose à faire est de copier la dernière version de votre port dans un nouveau répertoire de version, de mettre à jour la version et "port-version" les champs à mesure que vous avez besoin, puis de tester avec overlay-ports:

vcpkg install kitten --overlay-ports=ports/kitten/new-version.

Une fois que vous avez terminé vos tests, vous pouvez ajouter cette nouvelle version en haut de votre versions/k-/kitten.json:

{
  "versions": [
    {
      "version": "2.6.3",
      "port-version": 0,
      "path": "$/ports/kitten/2.6.3_0"
    },
    {
      "version": "2.6.2",
      "port-version": 0,
      "path": "$/ports/kitten/2.6.2_0"
    }
  ]
}

Ensuite, vous souhaiterez également modifier votre versions/baseline.json nouvelle version (n’oubliez pas de modifier les bases de référence existantes) :

{
  "2021-04-17": {
    "kitten": {
      "baseline": "2.6.3",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  },
  "2021-04-16": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  },
  "2021-04-15": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 1
    }
  }
}

Vous avez terminé !