Tester vos ports de Registre personnalisés à l’aide de vcpkg avec Azure DevOps

  • Article

Une fois que vous avez configuré un registre personnalisé de ports vcpkg, vous pouvez ajouter une intégration continue pour vérifier que toutes vos dépendances peuvent être générées avec succès.

Le registre vcpkg principal de Microsoft/vcpkg est testé par l’équipe vcpkg à l’aide d’un pipeline d’intégration continue (CI) avec Azure DevOps. Cela garantit que l’ajout de nouveaux packages ou la mise à jour des packages existants n’interrompt pas les consommateurs.

Dans cet article, nous vous montrons comment configurer un environnement CI pour tester les ports vcpkg dans votre propre registre.

Dans cet article, vous allez apprendre à effectuer les opérations suivantes :

  • Configurer un cache binaire et un cache de ressources pour votre pipeline Azure DevOps
  • Configurer un pipeline pour tester les ports de votre registre

Prérequis

Configurer un cache binaire et un cache de ressources pour vos pipelines Azure DevOps

La création d’une grande collection de ports est une tâche coûteuse en termes de temps et de puissance de calcul. Avant d’engager ci pour vos ports, nous vous recommandons vivement de configurer un cache binaire et un cache de ressources pour vos pipelines Azure DevOps.

Un cache binaire offre le plus d’avantages pour les scénarios CI en veillant à ce que les packages non modifiés ne soient pas reconstruits sur chaque exécution CI. Un cache de ressources miroir artefacts téléchargés pour vos packages pendant une exécution et utilise les artefacts mis en cache dans les exécutions suivantes. Il peut également aider à atténuer les problèmes où le référentiel amont n’est pas fiable : par exemple, une URL de téléchargement interrompue.

Pour obtenir des instructions détaillées sur la configuration de ces caches, lisez nos articles de mise en cache binaire et de mise en cache des ressources.

Exemple : Activer la mise en cache des ressources et binaires dans un pipeline Azure DevOps

steps: 
- task: NuGetAuthenticate@1

- script: $(Build.Repository.LocalPath)/vcpkg/vcpkg install --triplet=x64-windows
  displayName: some vcpkg task
  env:
    X_VCPKG_ASSET_SOURCES: "clear;x-azurl,https://my.domain.com/container,$(VcpkgAssetCache),readwrite"
    VCPKG_BINARY_SOURCES: "clear;nuget,https://my.domain.com/vcpkgBinaryCache/nuget/v3/index.json,readwrite"

Cet exemple montre comment configurer un cache binaire et un cache de ressources dans un pipeline Azure DevOps. Vous devez adapter cet extrait de code pour l’utiliser sur le fichier YAML de votre propre pipeline.

Décomposer cet extrait de code :

X_VCPKG_ASSET_SOURCES est la variable d’environnement utilisée pour configurer les caches de ressources dans vcpkg. Dans cet exemple, il est défini sur x-azurl,https://my.domain.com/container,$(VcpkgAssetCache),readwrite. Le x-azurl serveur principal indique à vcpkg d’utiliser un conteneur Stockage Azure comme fournisseur de stockage. Il x-azurl est suivi de trois paramètres séparés par des virgules (,).

  • https://my.domain.com/container est une URL de conteneur de stockage.
  • $(VcpkgAssetCache) est une variable secrète de pipeline qui contient un jeton SAP pour s’authentifier auprès du conteneur de stockage.
  • readwrite définit les autorisations de lecture et d’écriture pour le cache de ressources. Cela signifie que ce cache de ressources est utilisé pour stocker des artefacts ainsi que pour restaurer des artefacts à partir de celui-ci.

VCPKG_BINARY_SOURCES est la variable d’environnement utilisée pour configurer des caches binaires dans vcpkg. Dans cet exemple, il est défini sur clear;nuget,https://my.domain.com/vcpkgBinaryCache/nuget/v3/index.json,readwrite. Cela active le back-end NuGet pour le cache binaire à l’aide du flux NuGet sur https://my.domain.com/vcpkgBinaryCache/nuget/v3/index.json. Certaines étapes supplémentaires peuvent être nécessaires pour s’authentifier auprès de votre flux NuGet, lisez le tutoriel pour obtenir des instructions pour configurer l’authentification NuGet avec ADO.

La tâche suivante doit être ajoutée en l’état dans votre pipeline pour s’authentifier auprès de vos flux NuGet Azure Artifacts. Cette tâche doit également s’exécuter avant toute tâche impliquant vcpkg.

- task: NuGetAuthenticate@1

Si vous utilisez un autre hôte pour vos flux NuGet, lisez la documentation sur l’authentification de NuGet.

Apprenez-en davantage sur le fonctionnement de toutes ces fonctionnalités en lisant la documentation sur les fonctionnalités de cache de ressources et de cache binaire.

Configurer un pipeline pour tester les ports de votre registre

Une fois que vous avez configuré un cache binaire et un cache de ressources pour votre environnement CI, l’étape suivante consiste à configurer un pipeline pour tester tous les ports de votre registre. Vous pouvez décider si ce pipeline s’exécute selon une planification ou s’il est déclenché par de nouvelles validations ou demandes de tirage.

Le registre vcpkg principal utilise la vcpkg ci commande, qui a été adaptée aux besoins du projet vcpkg et n’est pas destinée à rester stable ou à être utilisée par les consommateurs de vcpkg. Par conséquent, il n’est pas adapté à l’utilisation pour tester vos propres registres vcpkg. Nous vous recommandons de suivre les étapes décrites dans cet article à la place.

Utiliser un fichier manifeste pour inclure tous vos ports

Au lieu d’utiliser la vcpkg ci commande, nous vous suggérons d’utiliser un fichier manifeste pour créer une build qui dépend de tous les packages de votre Registre.

L’exemple suivant crée un fichier manifeste pour tester tous les ports d’un registre vcpkg hypothétique. Remplacez la liste des dépendances pour inclure tous les ports de votre registre et placez-le à la racine de votre référentiel.

vcpkg.json

{
  "dependencies": [
    "beicode",
    "beison"
  ]
}

Vos propres ports peuvent avoir des dépendances sur le registre vcpkg principal ou d’autres registres tiers, auquel cas, vous devez ajouter ces registres dans un vcpkg-configuration.json fichier. Bien que vcpkg puisse résoudre les packages à partir du registre principal sans configuration supplémentaire, nous vous recommandons vivement de l’ajouter explicitement à la liste des registres à des fins de contrôle de version. Cela garantit que vous avez le contrôle de l’ensemble des versions de port sous-jacentes. Consultez la vcpkg x-update-baseline commande pour vous aider à gérer la base de référence de vos registres.

vcpkg-configuration.json

{
  "default-registry": null,
  "registries": [
    {
      "kind": "git",
      "repository": "https://github.com/Microsoft/vcpkg",
      "baseline": "42bb0d9e8d4cf33485afb9ee2229150f79f61a1f",
      "packages": "*"
    }
  ]
}

Pour en savoir plus, lisez les vcpkg.json articles et vcpkg-configuration.json référencez-les. Et la documentation en mode manifeste pour découvrir comment ces éléments fonctionnent ensemble.

Acquérir vcpkg dans votre pipeline Azure DevOps

Si vous utilisez vcpkg comme sous-module dans votre projet, vous pouvez obtenir le référentiel vcpkg à l’étape pour case activée out de votre propre projet, comme indiqué ci-dessous.

steps:
- checkout: self
  submodules: true

Sinon, vous devez acquérir vcpkg pour l’utiliser dans votre pipeline. Ajoutez les étapes suivantes pour cloner le référentiel vcpkg.

resources:
  repositories:
    - repository: vcpkgRepo
      type: github
      name: Microsoft/vcpkg
      endpoint: MyGitHubServiceConnection

steps:
  - checkout: vcpkgRepo

Pour cloner le référentiel vcpkg, vous devez définir une ressource de référentiel pour votre pipeline. L’extrait de code ci-dessous montre comment ajouter le référentiel vcpkg en tant que ressource, vous devez configurer un service Connecter ion pour connecter votre pipeline à GitHub.

Après case activée sortie du référentiel vcpkg en tant que sous-module ou en le clonant à partir de GitHub, vous devez exécuter le script de démarrage de vcpkg.

steps:
  - script: vcpkg/bootstrap-vcpkg.sh

Une fois ces étapes terminées, vous devez disposer d’un exécutable vcpkg à utiliser.

Exécuter l’installation de vcpkg pour générer vos ports

La dernière étape consiste à indiquer à vcpkg de générer tous vos ports. Vous avez peut-être remarqué que votre propre registre est absent de la vcpkg-configuration.json création de deux étapes ci-dessus. C’est pourquoi vous souhaitez tester la version des ports actuellement dans le répertoire de travail, par opposition aux versions publiées dans votre référentiel.

À cet objectif, vous devez ajouter les ports de votre registre en tant que ports de superposition en définissant la variable d’environnement sur le VCPKG_OVERLAY_PORTS répertoire de ports votre registre.

L’extrait de code ci-dessous montre comment configurer les ports de votre registre en tant que ports de superposition et s’exécute vcpkg install en mode manifeste pour installer tous vos ports personnalisés.

steps:
- script: $(Build.Repository.LocalPath)/vcpkg/vcpkg install
  env:
    X_VCPKG_ASSET_SOURCES: "clear;x-azurl,https://my.domain.com/container,$(VcpkgAssetCache),readwrite"
    VCPKG_BINARY_SOURCES: "clear;nuget,https://my.domain.com/demoBinaries/nuget/v3/index.json,readwrite"
    VCPKG_OVERLAY_PORTS: "$(Build.Repository.LocalPath)/ports"

Dans cet exemple, nous partons du principe que le vcpkg.json fichier est créé à la racine du référentiel de votre registre et que le référentiel vcpkg est ajouté en tant que sous-module.

La mise en place de tous les fichiers YAML de vos pipelines doit ressembler à ceci :

.azure-pipelines/test-ports.yml

trigger:
- main

pool:
  vmImage: windows-latest

steps:
- checkout: self
  submodules: true

- task: NuGetAuthenticate@1

- script: $(Build.Repository.LocalPath)/vcpkg/bootstrap-vcpkg.bat
  displayName: Bootstrap vcpkg

- script: $(Build.Repository.LocalPath)/vcpkg/vcpkg install --triplet=x64-windows
  env:
    X_VCPKG_ASSET_SOURCES: "clear;x-azurl,https://my.domain.com/container,$(VcpkgAssetCache),readwrite"
    VCPKG_BINARY_SOURCES: "clear;nuget,https://my.domain.com/demoBinaries/nuget/v3/index.json,readwrite"
    VCPKG_OVERLAY_PORTS: "$(Build.Repository.LocalPath)/ports"

Il s’agit de la structure de base d’un pipeline CI pour tester les ports de votre registre. Vous pouvez nécessiter un travail supplémentaire pour vous authentifier auprès de référentiels privés ou de votre flux NuGet.

Vous pouvez également ajouter des étapes pour automatiser la génération du vcpkg.json fichier ou une étape qui vérifie que les ports nouvellement ajoutés à votre Registre ne sont pas laissés hors des tests.

Étapes suivantes

Les articles suivants peuvent vous être utiles lors de la configuration d’un environnement CI.