Création de registres

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".

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.

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.

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 _).

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é !