Partager via

Tester vos ports de Registre personnalisés à l’aide de vcpkg avec GitHub Actions

  • Article

Une fois que vous avez configuré un registre personnalisé de ports vcpkg, vous pouvez ajouter Continous Integration 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 de l’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 vos workflows GitHub Actions
  • Configurer un flux de travail pour tester les ports de votre Registre

Prérequis

Configurer un cache binaire et un cache de ressources pour vos workflows GitHub Actions

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 flux de travail GitHub Action.

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 flux de travail GitHub Actions

steps:
  - name: Enable GitHub Actions Cache backend
    uses: actions/github-script@v7
    with:
      script: |
        core.exportVariable('ACTIONS_CACHE_URL', process.env.ACTIONS_CACHE_URL || '');
        core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');

  - name: some vcpkg task
    run: "${{ github.workspace }}/vcpkg/vcpkg install"
    env: 
      X_VCPKG_ASSET_SOURCES: "clear;x-azurl,https://my.domain.com/container,{{ secrets.SAS }},readwrite"
      VCPKG_BINARY_SOURCES: "clear;x-gha,readwrite"

Cet exemple montre comment configurer un cache binaire et un cache de ressources dans un workflow GitHub Actions. Vous devez adapter cet extrait de code pour l’utiliser sur le fichier YAML de votre propre flux de travail.

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,{{secrets.SAS}},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.
  • {{secrets.SAS}} est une variable secrète GitHub Actions 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;x-gha,readwrite. Cela active le serveur principal du cache GitHub Actions pour le cache binaire. Une étape supplémentaire est nécessaire dans votre flux de travail pour permettre à ce back-end de réussir.

L’étape suivante doit être incluse en l’état dans vos étapes de flux de travail GitHub Action. Cette étape exporte deux variables d’environnement requises par le x-gha back-end pour fonctionner et doit être exécutée avant toute tâche impliquant vcpkg.

- name: Enable GitHub Actions Cache backend
  uses: actions/github-script@v7
  with:
  script: |
    core.exportVariable('ACTIONS_CACHE_URL', process.env.ACTIONS_CACHE_URL || '');
    core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');

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 flux de travail 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 flux de travail pour tester tous les ports de votre registre. Vous pouvez décider si ce flux de travail s’exécute selon une planification ou s’il est déclenché par de nouvelles validations ou demandes d’extraction.

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 workflow GitHub Actions

Ensuite, vous devez acquérir vcpkg pour l’utiliser dans votre flux de travail. Ajoutez les étapes suivantes pour installer vcpkg.

steps:
- uses: actions/checkout@v4
  with:
    repository: "https://github.com/Microsoft/vcpkg"
    path: "vcpkg"

- name: Bootstrap vcpkg
  run: "${{ github.workspace }}/vcpkg/bootstrap-vcpkg.sh"
  shell: bash

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.

  - name: some vcpkg task
    run: "${{ github.workspace }}/vcpkg/vcpkg install"
    env: 
      X_VCPKG_ASSET_SOURCES: "clear;x-azurl,https://my.domain.com/container,{{ secrets.SAS }},readwrite"
      VCPKG_BINARY_SOURCES: "clear;x-gha,readwrite"
      VCPKG_OVERLAY_PORTS: "${{ github.workspace }}/ports"

Dans cet exemple, nous partons du principe que le vcpkg.json fichier est créé à la racine du référentiel de votre registre.

La mise en place de tous les fichiers YAML de votre flux de travail doit ressembler à ceci :

.github/workflows/test-ports.yml

name: Test vcpkg ports

on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["main"]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4
    
    - name: Acquire vcpkg
      uses: actions/checkout@v4
      with:
        repository: "Microsoft/vcpkg"
        path: vcpkg

    - name: Bootstrap vcpkg
      run: "${{ github.workspace }}/vcpkg/bootstrap-vcpkg.sh"
      shell: bash

    - name: Enable GitHub Actions Cache backend
      uses: actions/github-script@v7
      with:
        script: |
          core.exportVariable('ACTIONS_CACHE_URL', process.env.ACTIONS_CACHE_URL || '');
          core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');

    - name: Build ports
      run: ${{ github.workspace }}/vcpkg/vcpkg install
      env:
        X_VCPKG_ASSET_SOURCES: "clear;x-azurl,https://your.domain.com/container,${{ secrets.SAS }},readwrite"
        VCPKG_BINARY_SOURCES: "clear;x-gha,readwrite"
        VCPKG_OVERLAY_PORTS: "${{ github.workspace }}/ports"
      shell: bash

Il s’agit de la structure de base d’un flux de travail 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.