Тестирование пользовательских портов реестра с помощью vcpkg с помощью GitHub Actions

Статья
03/05/2024

После настройки пользовательского реестра портов vcpkg может потребоваться добавить континуозную интеграцию, чтобы убедиться, что все зависимости можно создать успешно.

Основной реестр vcpkg в Microsoft/vcpkg тестируется командой vcpkg с помощью непрерывной интеграции (CI) с Azure DevOps. Это гарантирует, что добавление новых пакетов или обновление существующих не прерывает работу потребителей.

В этой статье показано, как настроить среду CI для тестирования портов vcpkg в собственном реестре.

Из этой статьи вы узнаете следующее.

Настройка двоичного кэша и кэша ресурсов для рабочих процессов GitHub Actions
Настройка рабочего процесса для тестирования портов реестра

Необходимые компоненты

Учетная запись GitHub
Собственный реестр vcpkg Git
Завершение учебников по кэшированию двоичных файлов и ресурсов.
Знания о рабочих процессах GitHub Actions

Настройка двоичного кэша и кэша ресурсов для рабочих процессов GitHub Actions

Создание большого набора портов является дорогой задачей как с точки зрения времени, так и вычислительной мощности. Мы настоятельно рекомендуем перед привлечением CI для портов инвестировать в настройку двоичного кэша и кэша ресурсов для рабочих процессов GitHub Action.

Двоичный кэш обеспечивает наибольшее преимущество для сценариев CI, гарантируя, что неизмененные пакеты не перестроены во всех запусках CI. Кэш ресурсов зеркало артефакты, скачанные для пакетов во время выполнения, и используют кэшированные артефакты в последующих запусках. Это также может помочь устранить проблемы, когда репозиторий вышестоящий является ненадежным: например, сломанный URL-адрес загрузки.

Подробные инструкции по настройке этих кэшей см. в наших статьях об двоичном кэшировании и кэшировании ресурсов.

Пример. Включение кэширования активов и двоичных файлов в рабочем процессе 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"

В этом примере показано, как настроить двоичный кэш и кэш ресурсов в рабочем процессе GitHub Actions. Этот фрагмент следует адаптировать для использования в файле YAML собственного рабочего процесса.

Разбиение этого фрагмента кода:

X_VCPKG_ASSET_SOURCES — переменная среды, используемая для настройки кэшей ресурсов в vcpkg. В этом примере для него задано значение x-azurl,https://my.domain.com/container,{{secrets.SAS}},readwrite. Серверная x-azurl часть указывает vcpkg использовать контейнер служба хранилища Azure в качестве поставщика хранилища. За x-azurl ним следует три параметра, разделенные запятыми (,).

https://my.domain.com/container — ЭТО URL-адрес контейнера хранилища.
{{secrets.SAS}} — это переменная секрета GitHub Actions, содержащая маркер SAS для проверки подлинности в контейнере хранилища.
readwrite задает разрешения на чтение и запись для кэша ресурсов. Это означает, что этот кэш ресурсов используется для хранения артефактов, а также для восстановления артефактов из него.

VCPKG_BINARY_SOURCES — переменная среды, используемая для настройки двоичных кэшей в vcpkg. В этом примере для него задано значение clear;x-gha,readwrite. Это позволяет серверной части кэша действий GitHub для двоичного кэша. Дополнительный шаг требуется в рабочем процессе для успешного включения этой серверной части.

Следующий шаг должен быть включен как в рабочий процесс GitHub Action. На этом шаге экспортируются две переменные среды, необходимые серверной x-gha части для работы, и перед любой задачей, которая включает 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 || '');

Узнайте больше о том, как все эти действия работают, прочитав документацию по функциям кэша ресурсов и двоичного кэша .

Настройка рабочего процесса для тестирования портов реестра

После настройки двоичного кэша и кэша ресурсов для среды CI необходимо настроить рабочий процесс для тестирования всех портов реестра. Вы можете решить, выполняется ли этот рабочий процесс по расписанию или активируется ли он новыми фиксациями или запросами на вытягивание.

Основной реестр vcpkg использует vcpkg ci команду, которая была адаптирована к потребностям проекта vcpkg и не предназначена для сохранения стабильности или использования потребителями vcpkg. Таким образом, он не подходит для тестирования собственных реестров vcpkg. Мы рекомендуем выполнить действия, описанные в этой статье.

Использование файла манифеста для включения всех портов

Вместо использования vcpkg ci команды мы рекомендуем использовать файл манифеста для создания сборки, которая зависит от всех пакетов в реестре.

В следующем примере создается файл манифеста для тестирования всех портов в гипотетическом реестре vcpkg. Замените список зависимостей, чтобы включить все порты в реестр и поместить его в корневой каталог репозитория.

vcpkg.json

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

У ваших собственных портов могут быть зависимости от основного реестра vcpkg или других сторонних реестров, в этом случае необходимо добавить эти реестры в vcpkg-configuration.json файл. Хотя vcpkg может разрешать пакеты из основного реестра без дополнительной конфигурации, настоятельно рекомендуется явно добавить его в список реестров для целей управления версиями. Это гарантирует, что у вас есть контроль над набором базовых версий портов. Ознакомьтесь с командойvcpkg x-update-baseline, чтобы помочь управлять базовыми показателями реестров.

vcpkg-configuration.json

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

Дополнительные сведения см. в vcpkg.json статьях и vcpkg-configuration.json справочных статьях. И документация по режиму манифеста, чтобы узнать, как они работают вместе.

Получение vcpkg в рабочем процессе GitHub Actions

Затем необходимо получить vcpkg, чтобы использовать его в рабочем процессе. Добавьте следующие шаги для установки 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

После выполнения этих действий необходимо иметь исполняемый файл vcpkg для работы.

Запуск установки vcpkg для сборки портов

Последний шаг — сообщить vcpkg сборке всех портов. Возможно, вы заметили, что собственный реестр отсутствует в vcpkg-configuration.json созданном нескольких шагах выше. Причина заключается в том, что вы хотите протестировать версию портов в рабочем каталоге, а не версии, опубликованные в репозитории.

Для этой цели необходимо добавить порты реестра в качестве наложенных портов , задав VCPKG_OVERLAY_PORTS переменную среды в каталог реестра ports .

В приведенном ниже фрагменте показано, как настроить порты реестра как порты наложения и выполняться vcpkg install в режиме манифеста, чтобы установить все пользовательские порты.

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

В этом примере предполагается, что vcpkg.json файл создается в корневом каталоге репозитория реестра.

Объединение файлов YAML рабочего процесса должно выглядеть следующим образом:

.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

Это базовая структура рабочего процесса CI для тестирования портов реестра. Для проверки подлинности в частных репозиториях или в веб-канале NuGet может потребоваться дополнительная работа.

Вы также можете добавить шаги для автоматизации создания vcpkg.json файла или шага, который проверяет, что порты, добавленные в реестр, не остаются вне тестов.

Следующие шаги

При настройке среды CI могут быть полезны следующие статьи.

Поделиться через