Testare le porte del Registro di sistema personalizzate usando vcpkg con GitHub Actions

Dopo aver configurato un registro personalizzato di porte vcpkg, è possibile aggiungere l'integrazione continua per verificare che tutte le dipendenze possano essere compilate correttamente.

Il registro vcpkg principale in Microsoft/vcpkg viene testato dal team vcpkg usando l'integrazione continua (CI) con Azure DevOps. Ciò garantisce che l'aggiunta di nuovi pacchetti o l'aggiornamento di quelli esistenti non interrompa i consumer.

In questo articolo viene illustrato come configurare un ambiente CI per testare le porte vcpkg nel proprio registro.

In questo articolo si apprenderà come:

Prerequisiti

• Un account GitHub
• Registro Git vcpkg personalizzato
• Completamento delle esercitazioni sulla memorizzazione nella cache binaria e nella memorizzazione nella cache degli asset.
• Informazioni sui flussi di lavoro di GitHub Actions

Configurare una cache binaria e una cache degli asset per i flussi di lavoro di GitHub Actions

La creazione di una grande raccolta di porte è un'attività costosa sia in termini di tempo che di potenza di calcolo. Prima di coinvolgere ci per le porte, è consigliabile investire nella configurazione di una cache binaria e di una cache di asset per i flussi di lavoro di GitHub Action.

Una cache binaria offre il massimo vantaggio per gli scenari di integrazione continua, assicurandosi che i pacchetti non modificati non vengano ricompilati in ogni esecuzione ci. Una cache degli asset rispecchia gli artefatti scaricati per i pacchetti durante un'esecuzione e usa gli artefatti memorizzati nella cache nelle esecuzioni successive. Può anche aiutare a mitigare i problemi in cui il repository upstream non è affidabile, ad esempio un URL di download interrotto.

Per istruzioni dettagliate su come configurare queste cache, leggere gli articoli sulla memorizzazione nella cache binaria e sulla memorizzazione nella cache degli asset.

Esempio: Abilitare la memorizzazione nella cache di asset e binari in un flusso di lavoro di 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"

Questo esempio illustra come configurare una cache binaria e una cache degli asset in un flusso di lavoro di GitHub Actions. È necessario adattare questo frammento di codice da usare nel file YAML del flusso di lavoro.

Suddivisione di questo frammento di codice:

X_VCPKG_ASSET_SOURCES è la variabile di ambiente usata per configurare le cache degli asset in vcpkg. In questo esempio viene impostato su x-azurl,https://my.domain.com/container,{{secrets.SAS}},readwrite. Il x-azurl back-end indica a vcpkg di usare un contenitore Archiviazione di Azure come provider di archiviazione. l'oggetto x-azurl è seguito da tre parametri separati da virgole (,).

• https://my.domain.com/container è un URL del contenitore di archiviazione.
• {{secrets.SAS}} è una variabile privata di GitHub Actions che contiene un token di firma di accesso condiviso per l'autenticazione nel contenitore di archiviazione.
• readwrite imposta le autorizzazioni di lettura e scrittura per la cache degli asset. Ciò significa che questa cache degli asset viene usata per archiviare gli artefatti e per ripristinare gli artefatti da esso.

VCPKG_BINARY_SOURCES è la variabile di ambiente usata per configurare le cache binarie in vcpkg. In questo esempio viene impostato su clear;x-gha,readwrite. In questo modo viene abilitato il back-end della cache di GitHub Actions per la cache binaria. Per abilitare correttamente questo back-end, è necessario un passaggio aggiuntivo nel flusso di lavoro.

Il passaggio seguente deve essere incluso così come è nei passaggi del flusso di lavoro di GitHub Action. Questo passaggio esporta due variabili di ambiente richieste dal x-gha back-end e deve essere eseguito prima di qualsiasi attività che coinvolge 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 || '');

Per altre informazioni sul funzionamento di tutti questi elementi, leggere la documentazione sulle funzionalità della cache degli asset e della cache binaria.

Configurare un flusso di lavoro per testare le porte del Registro di sistema

Dopo aver configurato una cache binaria e una cache degli asset per l'ambiente CI, il passaggio successivo consiste nel configurare un flusso di lavoro per testare tutte le porte del Registro di sistema. È possibile decidere se questo flusso di lavoro viene eseguito in base a una pianificazione o se viene attivato da nuovi commit o richieste pull.

Il registro vcpkg principale usa il vcpkg ci comando , che è stato personalizzato in base alle esigenze del progetto vcpkg e non è destinato a rimanere stabile o essere usato dai consumer di vcpkg. Di conseguenza, non è adatto per il test dei registri vcpkg personalizzati. È consigliabile seguire invece i passaggi descritti in questo articolo.

Usare un file manifesto per includere tutte le porte

Anziché usare il vcpkg ci comando , è consigliabile usare un file manifesto per creare una compilazione che dipende da tutti i pacchetti nel Registro di sistema.

Nell'esempio seguente viene creato un file manifesto per testare tutte le porte in un registro vcpkg ipotetico. Sostituire l'elenco delle dipendenze per includere tutte le porte nel Registro di sistema e inserirle nella radice del repository.

vcpkg.json

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

Le porte personalizzate possono avere dipendenze dal registro vcpkg principale o da altri registri di terze parti, nel qual caso è necessario aggiungere tali registri in un vcpkg-configuration.json file. Anche se vcpkg può risolvere i pacchetti dal Registro di sistema principale senza configurazione aggiuntiva, è consigliabile aggiungerlo in modo esplicito all'elenco registri per scopi di controllo della versione. In questo modo si garantisce il controllo del set di versioni delle porte sottostanti. Consultare il vcpkg x-update-baseline comando per facilitare la gestione della baseline dei registri.

vcpkg-configuration.json

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

Per altre informazioni, vedere gli vcpkg.json articoli di riferimento e vcpkg-configuration.json . E la documentazione relativa alla modalità manifesto per informazioni su come interagiscono.

Acquisire vcpkg nel flusso di lavoro di GitHub Actions

Successivamente, è necessario acquisire vcpkg per usarlo nel flusso di lavoro. Aggiungere i passaggi seguenti per installare 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

Al termine di questi passaggi, è necessario avere un eseguibile vcpkg da usare.

Eseguire vcpkg install per compilare le porte

L'ultimo passaggio consiste nell'indicare a vcpkg di compilare tutte le porte. Si potrebbe aver notato che il proprio registro è assente dal vcpkg-configuration.json creato un paio di passaggi precedenti. Il motivo è che si vuole testare la versione delle porte attualmente nella directory di lavoro anziché le versioni pubblicate nel repository.

A tale scopo, è necessario aggiungere le porte del Registro di sistema come porte di sovrapposizione impostando la variabile di ambiente sulla VCPKG_OVERLAY_PORTS directory del Registro di ports sistema.

Il frammento di codice seguente illustra come configurare le porte del Registro di sistema come porte di sovrapposizione ed è in esecuzione vcpkg install in modalità manifesto per installare tutte le porte personalizzate.

  - 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 questo esempio si presuppone che il vcpkg.json file venga creato nella radice del repository del Registro di sistema.

L'aspetto del file YAML del flusso di lavoro dovrebbe essere simile al seguente:

.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

Si tratta della struttura di base per un flusso di lavoro ci per testare le porte del Registro di sistema. Potrebbe essere necessario eseguire alcune operazioni aggiuntive per l'autenticazione nei repository privati o nel feed NuGet.

È anche possibile aggiungere passaggi per automatizzare la generazione del vcpkg.json file o un passaggio che verifica che le porte appena aggiunte al Registro di sistema non vengano interrotte dai test.

Passaggi successivi

Gli articoli seguenti possono essere utili per la configurazione di un ambiente CI.

• Eseguire l'autenticazione in registri Git privati
• Configurare una cache binaria usando GHA Cache
• Configurare una cache degli asset
• Informazioni di riferimento sulla cache binaria
• Informazioni di riferimento sulla cache degli asset
• Porte sovrapposte
• Modalità manifesto
• vcpkg.json
• vcpkg-configuration.json
• Variabili di ambiente di configurazione vcpkg