Création de registres
Pour plus d’informations sur la consommation de registres, consultez Utilisation de registres.
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.
À 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 écrivezgit 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.
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.
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 !!
À 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.json
qui 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épertoireversions
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"
}
]
}
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é !
Commentaires sur vcpkg
vcpkg est un projet open source. Sélectionnez un lien pour fournir des commentaires :