Testen Der benutzerdefinierten Registrierungsports mithilfe von vcpkg mit GitHub-Aktionen

Nachdem Sie eine benutzerdefinierte Registrierung von vcpkg-Ports eingerichtet haben, können Sie continous Integration hinzufügen, um zu überprüfen, ob alle Abhängigkeiten erfolgreich erstellt werden können.

Die Standard vcpkg registry at Microsoft/vcpkg is test by the vcpkg team using continuous integration (CI) with Azure DevOps. Dadurch wird sichergestellt, dass das Hinzufügen neuer Pakete oder das Aktualisieren vorhandener Pakete die Verbraucher nicht unterbrechen.

In diesem Artikel erfahren Sie, wie Sie eine CI-Umgebung einrichten, um die vcpkg-Ports in Ihrer eigenen Registrierung zu testen.

In diesem Artikel lernen Sie Folgendes:

• Einrichten eines binären Caches und Eines Ressourcencaches für Ihre GitHub-Aktionen-Workflows
• Einrichten eines Workflows zum Testen der Ports Ihrer Registrierung

Voraussetzungen

• GitHub-Konto
• Ihre eigene vcpkg Git-Registrierung
• Abschluss der Lernprogramme für binäre Zwischenspeicherung und Ressourcenzwischenspeicherung.
• Wissen über GitHub Actions-Workflows

Einrichten eines binären Caches und Eines Ressourcencaches für Ihre GitHub-Aktionen-Workflows

Das Erstellen einer großen Sammlung von Ports ist eine teure Aufgabe sowohl in Bezug auf Zeit als auch Rechenleistung. Es wird dringend empfohlen, dass Sie vor der Einbindung von CI für Ihre Ports in das Einrichten eines binären Caches und einen Objektcache für Ihre GitHub Action-Workflows investieren.

Ein Binärer Cache bietet den größten Vorteil für CI-Szenarien, indem sichergestellt wird, dass nicht geänderte Pakete nicht auf jeder CI-Ausführung neu erstellt werden. Ein Objektcache Spiegel Artefakte, die während einer Ausführung für Ihre Pakete heruntergeladen wurden, und verwendet die zwischengespeicherten Artefakte in nachfolgenden Ausführungen. Es kann auch helfen, Probleme zu beheben, bei denen das upstream-Repository unzuverlässig ist: z. B. eine fehlerhafte Download-URL.

Ausführliche Anweisungen zum Einrichten dieser Caches finden Sie in unseren Artikeln zur binären Zwischenspeicherung und Zum Zwischenspeichern von Objekten.

Beispiel: Aktivieren der Objekt- und Binären Zwischenspeicherung in einem GitHub-Aktionsworkflow

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"

In diesem Beispiel wird gezeigt, wie Sie einen binären Cache und einen Objektcache in einem GitHub Actions-Workflow einrichten. Sie sollten diesen Codeausschnitt so anpassen, dass er in der YAML-Datei Ihres eigenen Workflows verwendet wird.

Aufschlüsselung dieses Codeausschnitts:

X_VCPKG_ASSET_SOURCES ist die Umgebungsvariable, die zum Konfigurieren von Objektcaches in vcpkg verwendet wird. In diesem Beispiel ist sie auf x-azurl,https://my.domain.com/container,{{secrets.SAS}},readwrite. Das x-azurl Back-End weist vcpkg an, einen Azure Storage-Container als Speicheranbieter zu verwenden. Gefolgt x-azurl von drei Parametern, die durch Kommas (,) getrennt sind.

• https://my.domain.com/container ist eine Speichercontainer-URL.
• {{secrets.SAS}} ist eine geheime GitHub Actions-Variable, die ein SAS-Token zum Authentifizieren beim Speichercontainer enthält.
• readwrite legt Lese- und Schreibberechtigungen für den Objektcache fest. Dies bedeutet, dass dieser Ressourcencache zum Speichern von Artefakten sowie zum Wiederherstellen von Artefakten verwendet wird.

VCPKG_BINARY_SOURCES ist die Umgebungsvariable, die zum Konfigurieren von binären Caches in vcpkg verwendet wird. In diesem Beispiel ist sie auf clear;x-gha,readwrite. Dadurch wird das GitHub Actions Cache-Back-End für den binären Cache aktiviert. Ein zusätzlicher Schritt ist in Ihrem Workflow erforderlich, um dieses Back-End erfolgreich zu aktivieren.

Der folgende Schritt sollte wie in Ihren GitHub Action-Workflowschritten enthalten sein. In diesem Schritt werden zwei Umgebungsvariablen exportiert, die x-gha vom Back-End benötigt werden, um zu funktionieren, und sollte vor jeder Aufgabe ausgeführt werden, die vcpkg umfasst.

- 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 || '');

Erfahren Sie mehr darüber, wie all diese Arbeiten funktionieren, indem Sie die Dokumentation zu den Features des Objektcaches und binären Caches lesen.

Einrichten eines Workflows zum Testen der Ports Ihrer Registrierung

Nachdem Sie einen binären Cache und einen Objektcache für Ihre CI-Umgebung eingerichtet haben, besteht der nächste Schritt darin, einen Workflow einzurichten, um alle Ports Ihrer Registrierung zu testen. Sie können entscheiden, ob dieser Workflow in einem Zeitplan ausgeführt wird oder ob er durch neue Commits oder Pullanforderungen ausgelöst wird.

Die Standard vcpkg-Registrierung verwendet den vcpkg ci Befehl, der auf die Anforderungen des vcpkg-Projekts zugeschnitten wurde und nicht für die Erneutes Standard stabil ist oder von Verbrauchern von vcpkg verwendet werden soll. Daher ist es nicht geeignet, ihre eigenen vcpkg-Registrierungen zu testen. Es wird empfohlen, stattdessen die in diesem Artikel beschriebenen Schritte auszuführen.

Verwenden einer Manifestdatei zum Einschließen aller Ports

Anstatt den vcpkg ci Befehl zu verwenden, empfehlen wir die Verwendung einer Manifestdatei zum Erstellen eines Builds, der von allen Paketen in Ihrer Registrierung abhängt.

Im folgenden Beispiel wird eine Manifestdatei erstellt, um alle Ports in einer hypothetischen vcpkg-Registrierung zu testen. Ersetzen Sie die Liste der Abhängigkeiten, um alle Ports in Ihre Registrierung einzuschließen, und platzieren Sie sie im Stammverzeichnis Ihres Repositorys.

vcpkg.json

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

Ihre eigenen Ports verfügen möglicherweise über Abhängigkeiten von der Standard vcpkg-Registrierung oder anderen Drittanbieterregistrierungen, in diesem Fall müssen Sie diese Registrierungen in einer vcpkg-configuration.json Datei hinzufügen. Während vcpkg Pakete aus der Standard Registrierung ohne zusätzliche Konfiguration auflösen kann, wird dringend empfohlen, sie explizit zur Registrierungsliste für Versionssteuerungszwecke hinzuzufügen. Dadurch wird sichergestellt, dass Sie die Kontrolle über die Gruppe der zugrunde liegenden Portversionen haben. Sehen Sie sich den vcpkg x-update-baseline Befehl an, um den Basisplan Ihrer Registrierungen zu verwalten.

vcpkg-configuration.json

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

Lesen Sie die vcpkg.json Artikel und vcpkg-configuration.json referenzieren Sie, um mehr zu erfahren. Und in der Manifestmodusdokumentation erfahren Sie, wie diese zusammenarbeiten.

Erwerben von vcpkg im GitHub-Aktionsworkflow

Als Nächstes müssen Sie vcpkg erwerben, um es in Ihrem Workflow zu verwenden. Fügen Sie die folgenden Schritte zum Installieren von vcpkg hinzu.

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

Nach Abschluss dieser Schritte sollten Sie über eine vcpkg-ausführbare Datei verfügen, mit der sie arbeiten kann.

Ausführen der vcpkg-Installation zum Erstellen Ihrer Ports

Der letzte Schritt besteht darin, vcpkg anweisen, alle Ports zu erstellen. Möglicherweise haben Sie bemerkt, dass Ihre eigene Registrierung bei den vcpkg-configuration.json oben erstellten Schritten nicht vorhanden ist. Der Grund dafür ist, dass Sie die Version der Ports testen möchten, die sich derzeit im Arbeitsverzeichnis befinden, im Gegensatz zu den versionen, die in Ihrem Repository veröffentlicht wurden.

Zu diesem Zweck müssen Sie die Ports Ihrer Registrierung als Überlagerungsports hinzufügen, indem Sie die VCPKG_OVERLAY_PORTS Umgebungsvariable auf das ports Verzeichnis Ihrer Registrierung festlegen.

Der folgende Codeausschnitt zeigt, wie Sie die Ports Ihrer Registrierung als Überlagerungsports einrichten und im Manifestmodus ausgeführt werden vcpkg install , um alle benutzerdefinierten Ports zu installieren.

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

In diesem Beispiel wird davon ausgegangen, dass die vcpkg.json Datei im Stammverzeichnis Des Repositorys Ihrer Registrierung erstellt wird.

Das Zusammensetzen der YAML-Datei Ihres Workflows sollte etwa wie folgt aussehen:

.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

Dies ist die grundlegende Struktur für einen CI-Workflow zum Testen der Ports Ihrer Registrierung. Möglicherweise benötigen Sie zusätzliche Arbeit, um sich bei privaten Repositorys oder ihrem NuGet-Feed zu authentifizieren.

Sie können auch Schritte hinzufügen, um die Generierung der vcpkg.json Datei zu automatisieren, oder einen Schritt, der überprüft, ob die neu zu Ihrer Registrierung hinzugefügten Ports nicht aus den Tests herausgelassen werden.

Nächste Schritte

Die folgenden Artikel können bei der Einrichtung einer CI-Umgebung hilfreich sein.

• Authentifizieren bei privaten Git-Registrierungen
• Einrichten eines Binärcaches mithilfe des GHA-Caches
• Einrichten eines Objektcaches
• Binärer Cacheverweis
• Referenz zum Ressourcencache
• Überlagerungsports
• Manifestmodus
• vcpkg.json
• vcpkg-configuration.json
• vcpkg-Konfigurationsumgebungsvariablen