Udostępnij za pośrednictwem

Testowanie niestandardowych portów rejestru przy użyciu narzędzia vcpkg za pomocą funkcji GitHub Actions

  • Artykuł

Po skonfigurowaniu niestandardowego rejestru portów vcpkg możesz dodać ciągłą integrację, aby sprawdzić, czy wszystkie zależności można pomyślnie skompilować.

Główny rejestr vcpkg w firmie Microsoft/vcpkg jest testowany przez zespół vcpkg przy użyciu ciągłej integracji (CI) z usługą Azure DevOps. Dzięki temu dodanie nowych pakietów lub zaktualizowanie istniejących nie spowoduje przerwania użytkowników.

W tym artykule pokazano, jak skonfigurować środowisko ciągłej integracji w celu przetestowania portów vcpkg we własnym rejestrze.

Z tego artykułu dowiesz się, jak wykonywać następujące elementy:

  • Konfigurowanie binarnej pamięci podręcznej i pamięci podręcznej zasobów dla przepływów pracy funkcji GitHub Actions
  • Konfigurowanie przepływu pracy w celu przetestowania portów rejestru

Wymagania wstępne

Konfigurowanie binarnej pamięci podręcznej i pamięci podręcznej zasobów dla przepływów pracy funkcji GitHub Actions

Tworzenie dużej kolekcji portów jest kosztownym zadaniem zarówno w zakresie czasu, jak i mocy obliczeniowej. Zdecydowanie zalecamy, aby przed angażowaniem ciągłej integracji dla portów zainwestować w konfigurowanie binarnej pamięci podręcznej i pamięci podręcznej zasobów dla przepływów pracy akcji usługi GitHub.

Pamięć podręczna binarna zapewnia największą korzyść w scenariuszach ciągłej integracji, zapewniając, że niezmodyfikowane pakiety nie są komkompilowane w każdym uruchomieniu ciągłej integracji. Pamięć podręczna zasobów dubluje artefakty pobierane dla pakietów podczas przebiegu i używa buforowanych artefaktów w kolejnych uruchomieniach. Może również pomóc w rozwiązywaniu problemów, w których repozytorium nadrzędne jest zawodne: na przykład uszkodzony adres URL pobierania.

Aby uzyskać szczegółowe instrukcje dotyczące konfigurowania tych pamięci podręcznych, przeczytaj artykuły dotyczące buforowania binarnego i buforowania zasobów.

Przykład: włączanie buforowania elementów zawartości i plików binarnych w przepływie pracy funkcji 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"

W tym przykładzie pokazano, jak skonfigurować binarną pamięć podręczną i pamięć podręczną zasobów w przepływie pracy funkcji GitHub Actions. Ten fragment kodu należy dostosować do użycia w pliku YAML własnego przepływu pracy.

Podzielenie tego fragmentu kodu:

X_VCPKG_ASSET_SOURCES to zmienna środowiskowa używana do konfigurowania pamięci podręcznych zasobów w narzędziu vcpkg. W tym przykładzie ustawiono wartość x-azurl,https://my.domain.com/container,{{secrets.SAS}},readwrite. Zaplecze x-azurl instruuje program vcpkg, aby używał kontenera usługi Azure Storage jako dostawcy magazynu. Następuje x-azurl po nim trzy parametry rozdzielone przecinkami (,).

  • https://my.domain.com/container to adres URL kontenera magazynu.
  • {{secrets.SAS}} to zmienna wpisów tajnych funkcji GitHub Actions zawierająca token SAS do uwierzytelniania w kontenerze magazynu.
  • readwrite ustawia uprawnienia do odczytu i zapisu dla pamięci podręcznej zasobów. Oznacza to, że ta pamięć podręczna zasobów jest używana do przechowywania artefaktów oraz przywracania artefaktów z niej.

VCPKG_BINARY_SOURCES to zmienna środowiskowa używana do konfigurowania binarnych pamięci podręcznych w narzędziu vcpkg. W tym przykładzie ustawiono wartość clear;x-gha,readwrite. Umożliwia to zaplecze pamięci podręcznej funkcji GitHub Actions dla pamięci podręcznej binarnej. Dodatkowy krok jest wymagany w przepływie pracy w celu pomyślnego włączenia tego zaplecza.

Poniższy krok powinien zostać uwzględniony zgodnie z instrukcjami przepływu pracy akcji usługi GitHub. Ten krok eksportuje dwie zmienne środowiskowe wymagane przez x-gha zaplecze do pracy i powinny być uruchamiane przed każdym zadaniem, które obejmuje program 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 || '');

Dowiedz się więcej o tym, jak działają wszystkie te elementy, czytając dokumentację dotyczącą funkcji pamięci podręcznej zasobów i binarnej pamięci podręcznej .

Konfigurowanie przepływu pracy w celu przetestowania portów rejestru

Po skonfigurowaniu binarnej pamięci podręcznej i pamięci podręcznej zasobów dla środowiska ciągłej integracji następnym krokiem jest skonfigurowanie przepływu pracy w celu przetestowania wszystkich portów rejestru. Możesz zdecydować, czy ten przepływ pracy jest uruchamiany zgodnie z harmonogramem, czy też jest wyzwalany przez nowe zatwierdzenia lub żądania ściągnięcia.

Główny rejestr vcpkg używa vcpkg ci polecenia , które zostało dostosowane do potrzeb projektu vcpkg i nie ma na celu pozostania stabilne lub używane przez konsumentów vcpkg. W związku z tym nie nadaje się do testowania własnych rejestrów vcpkg. Zalecamy wykonanie kroków opisanych w tym artykule.

Dołączanie wszystkich portów za pomocą pliku manifestu

Zamiast używać polecenia, zalecamy użycie pliku manifestu vcpkg ci do utworzenia kompilacji, która zależy od wszystkich pakietów w rejestrze.

Poniższy przykład tworzy plik manifestu w celu przetestowania wszystkich portów w hipotetycznym rejestrze vcpkg. Zastąp listę zależności, aby uwzględnić wszystkie porty w rejestrze i umieścić je w katalogu głównym repozytorium.

vcpkg.json

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

Twoje własne porty mogą mieć zależności od głównego rejestru vcpkg lub innych rejestrów innych firm, w tym przypadku należy dodać te rejestry w vcpkg-configuration.json pliku. Mimo że program vcpkg może rozpoznawać pakiety z głównego rejestru bez dodatkowej konfiguracji, zdecydowanie zalecamy jawne dodanie go do listy rejestrów na potrzeby kontroli wersji. Dzięki temu masz kontrolę nad zestawem bazowych wersji portów. Zapoznaj się z poleceniemvcpkg x-update-baseline, aby ułatwić zarządzanie punktem odniesienia rejestrów.

vcpkg-configuration.json

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

vcpkg.json Przeczytaj artykuły i vcpkg-configuration.json referencyjne, aby dowiedzieć się więcej. Zapoznaj się z dokumentacją trybu manifestu, aby dowiedzieć się, jak działają one razem.

Uzyskiwanie narzędzia vcpkg w przepływie pracy funkcji GitHub Actions

Następnie należy uzyskać narzędzie vcpkg, aby używać go w przepływie pracy. Dodaj następujące kroki, aby zainstalować narzędzie 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 wykonaniu tych kroków należy pracować z plikiem wykonywalnym vcpkg.

Uruchamianie instalacji programu vcpkg w celu skompilowania portów

Ostatnim krokiem jest poinformowanie programu vcpkg o utworzeniu wszystkich portów. Być może zauważysz, że twój własny rejestr jest nieobecny w vcpkg-configuration.json utworzonym kilku krokach powyżej. Przyczyną jest to, że chcesz przetestować wersję portów aktualnie w katalogu roboczym, w przeciwieństwie do wersji opublikowanych w repozytorium.

W tym celu należy dodać porty rejestru jako porty nakładki, ustawiając zmienną VCPKG_OVERLAY_PORTS środowiskową w katalogu rejestru ports .

Poniższy fragment kodu przedstawia sposób konfigurowania portów rejestru jako portów nakładki i uruchamiania vcpkg install w trybie manifestu w celu zainstalowania wszystkich portów niestandardowych.

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

W tym przykładzie przyjęto założenie, że vcpkg.json plik jest tworzony w katalogu głównym repozytorium rejestru.

Umieszczenie pliku YAML przepływu pracy powinno wyglądać podobnie do następującego:

.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

Jest to podstawowa struktura przepływu pracy ciągłej integracji do testowania portów rejestru. Może być wymagana dodatkowa praca w celu uwierzytelnienia w repozytoriach prywatnych lub w kanale informacyjnym NuGet.

Możesz również dodać kroki automatyzacji generowania vcpkg.json pliku lub kroku sprawdzającego, czy porty nowo dodane do rejestru nie są pominięte w testach.

Następne kroki

Poniższe artykuły mogą być przydatne podczas konfigurowania środowiska ciągłej integracji.