Testování vlastních portů registru pomocí nástroje vcpkg s GitHub Actions

Jakmile nastavíte vlastní registr portů vcpkg, můžete přidat integraci Continous, abyste ověřili, že všechny závislosti lze úspěšně sestavit.

Hlavní registr vcpkg v Microsoftu/vcpkg testuje tým vcpkg pomocí kontinuální integrace (CI) s Azure DevOps. Tím se zajistí, že přidání nových balíčků nebo aktualizace stávajících balíčků neporuší uživatele.

V tomto článku vám ukážeme, jak nastavit prostředí CI pro testování portů vcpkg ve vašem vlastním registru.

V tomto článku se naučíte:

• Nastavení binární mezipaměti a mezipaměti prostředků pro pracovní postupy GitHub Actions
• Nastavení pracovního postupu pro otestování portů registru

Požadavky

• Účet GitHub
• Váš vlastní registr vcpkg Git
• Dokončení kurzů ukládání do binární mezipaměti a ukládání prostředků do mezipaměti .
• Znalost pracovních postupů GitHub Actions

Nastavení binární mezipaměti a mezipaměti prostředků pro pracovní postupy GitHub Actions

Vytvoření velké kolekce portů je nákladná úloha z hlediska času i výpočetního výkonu. Důrazně doporučujeme, abyste před zapojením CI pro vaše porty investovali do nastavení binární mezipaměti a mezipaměti prostředků pro pracovní postupy GitHub Action.

Binární mezipaměť poskytuje největší výhodu pro scénáře CI tím, že zajišťuje, aby se neupravené balíčky znovu nevystavily při každém spuštění CI. Mezipaměť prostředků zrcadlí artefakty stažené pro balíčky během spuštění a použije artefakty uložené v mezipaměti v následných spuštěních. Může také pomoct zmírnit problémy, kdy upstreamové úložiště nespolehlivé: například nefunkční adresa URL pro stahování.

Podrobné pokyny k nastavení těchto mezipamětí najdete v článcích o ukládání binární mezipaměti a ukládání prostředků do mezipaměti .

Příklad: Povolení prostředku a binární mezipaměti v pracovním postupu 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"

Tento příklad ukazuje, jak nastavit binární mezipaměť a mezipaměť prostředků v pracovním postupu GitHub Actions. Tento fragment kódu byste měli přizpůsobit tak, aby se používal v souboru YAML vlastního pracovního postupu.

Rozdělení tohoto fragmentu kódu:

X_VCPKG_ASSET_SOURCES je proměnná prostředí použitá ke konfiguraci mezipaměti prostředků v vcpkg. V tomto příkladu je nastavena na x-azurl,https://my.domain.com/container,{{secrets.SAS}},readwritehodnotu . Back-end x-azurl dává vcpkg pokyn, aby jako poskytovatele úložiště použil kontejner Azure Storage. Za ním x-azurl následují tři parametry oddělené čárkami (,).

• https://my.domain.com/container je adresa URL kontejneru úložiště.
• {{secrets.SAS}} je tajná proměnná GitHub Actions, která obsahuje token SAS pro ověření v kontejneru úložiště.
• readwrite nastaví oprávnění ke čtení a zápisu pro mezipaměť prostředků. To znamená, že tato mezipaměť prostředků se používá k ukládání artefaktů i k obnovení artefaktů z ní.

VCPKG_BINARY_SOURCES je proměnná prostředí použitá ke konfiguraci binárních mezipamětí v vcpkg. V tomto příkladu je nastavena na clear;x-gha,readwritehodnotu . To umožňuje back-end mezipaměti GitHub Actions pro binární mezipaměť. Pro úspěšné povolení tohoto back-endu je ve vašem pracovním postupu potřeba další krok.

Následující krok by se měl zahrnout tak, jak je součástí kroků pracovního postupu GitHub Action. Tento krok exportuje dvě proměnné prostředí vyžadované back-endem x-gha , aby fungovaly, a měly by být spuštěny před jakoukoli úlohou, která zahrnuje 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 || '');

Další informace o tom, jak všechny tyto funkce fungují, najdete v dokumentaci k mezipaměti prostředků a funkcím binární mezipaměti.

Nastavení pracovního postupu pro otestování portů registru

Po nastavení binární mezipaměti a mezipaměti prostředků pro vaše prostředí CI je dalším krokem nastavení pracovního postupu pro otestování všech portů registru. Můžete se rozhodnout, jestli se tento pracovní postup spouští podle plánu, nebo jestli je aktivovaný novými potvrzeními nebo žádostmi o přijetí změn.

Hlavní registr vcpkg používá vcpkg ci příkaz, který je přizpůsobený potřebám projektu vcpkg a není určen k tomu, aby zůstal stabilní nebo aby ho používali spotřebitelé vcpkg. Proto se nehodí k testování vlastních registrů vcpkg. Doporučujeme místo toho postupovat podle kroků uvedených v tomto článku.

Zahrnutí všech portů pomocí souboru manifestu

Místo použití vcpkg ci příkazu doporučujeme k vytvoření sestavení, které závisí na všech balíčcích ve vašem registru, použít soubor manifestu.

Následující příklad vytvoří soubor manifestu pro otestování všech portů v hypotetické registru vcpkg. Nahraďte seznam závislostí, které budou zahrnovat všechny porty v registru, a umístěte ho do kořenového adresáře úložiště.

vcpkg.json

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

Vlastní porty můžou mít závislosti na hlavním registru vcpkg nebo jiných registrech třetích stran, v takovém případě je potřeba tyto registry přidat do vcpkg-configuration.json souboru. I když nástroj vcpkg dokáže přeložit balíčky z hlavního registru bez další konfigurace, důrazně doporučujeme, abyste je explicitně přidali do seznamu registrů pro účely správy verzí. Tím se zajistí, že máte kontrolu nad sadou základních verzí portů. Podívejte se na příkaz, vcpkg x-update-baseline který vám pomůže se správou směrného plánu vašich registrů.

vcpkg-configuration.json

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

Další informace najdete v vcpkg.json článcích s referenčními informacemi.vcpkg-configuration.json A dokumentaci k režimu manifestu, kde se dozvíte, jak tyto postupy spolupracují.

Získání vcpkg v pracovním postupu GitHub Actions

Dále potřebujete získat vcpkg, abyste ho mohli použít ve svém pracovním postupu. Přidejte následující kroky pro instalaci 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

Po dokončení těchto kroků byste měli mít spustitelný soubor vcpkg, se kterým chcete pracovat.

Spuštění instalace vcpkg pro sestavení portů

Posledním krokem je informovat vcpkg, aby se vytvořily všechny porty. Možná jste si všimli, že váš vlastní registr chybí ve vcpkg-configuration.json vytvořeném několika krocích výše. Důvodem je, že chcete otestovat verzi portů, které jsou aktuálně v pracovním adresáři, a ne verze publikované ve vašem úložišti.

Pro tento cíl musíte přidat porty registru jako překryvné porty nastavením VCPKG_OVERLAY_PORTS proměnné prostředí do adresáře registru ports .

Následující fragment kódu ukazuje, jak nastavit porty registru jako překryvné porty a spustit vcpkg install v režimu manifestu pro instalaci všech vlastních portů.

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

V tomto příkladu předpokládáme, že vcpkg.json se soubor vytvoří v kořenovém adresáři úložiště vašeho registru.

Když soubor YAML pracovního postupu umístíte dohromady, měl by vypadat nějak takto:

.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

Toto je základní struktura pracovního postupu CI pro otestování portů registru. Pro ověření v privátních úložištích nebo v informačním kanálu NuGet můžete vyžadovat další práci.

Můžete také přidat kroky pro automatizaci generování vcpkg.json souboru nebo kroku, který ověřuje, že porty nově přidané do registru nejsou vynechány z testů.

Další kroky

Při nastavování prostředí CI vám můžou být užitečné následující články.

• Ověřování u privátních registrů Git
• Nastavení binární mezipaměti pomocí mezipaměti GHA Cache
• Nastavení mezipaměti prostředků
• Referenční informace k binární mezipaměti
• Referenční informace k mezipaměti prostředků
• Překryvné porty
• Režim manifestu
• vcpkg.json
• vcpkg-configuration.json
• Proměnné konfiguračního prostředí vcpkg