Тестируйте ваши пользовательские порты реестра с помощью vcpkg и GitHub Actions

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

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

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

В этой статье вы узнаете, как настроить рабочий процесс CI для реестра, работающего в GitHub Actions:

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

Предпосылки

• Учетная запись GitHub
• Реестр vcpkg Git
• Ознакомьтесь с руководством по кэшированию двоичных файлов
• Ознакомьтесь с руководством по кэшированию ресурсов

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

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

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

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

Пример. Включение кэширования активов и двоичных файлов в рабочем процессе GitHub Actions

env:
  FEED_URL: https://nuget.pkg.github.com/<OWNER>/index.json

steps:
  - name: Install vcpkg ports
    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;nuget,https://nuget.pkg.github.com/<OWNER>/index.json,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 as-is. На этом шаге экспортируются две переменные среды, необходимые для работы серверной 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 необходимо настроить рабочий процесс для тестирования всех портов реестра. Вы можете решить, выполняется ли этот рабочий процесс по расписанию или активируется ли он новыми коммитами или pull requests.

Основной реестр 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 могут быть полезны следующие статьи.

• Проверка подлинности в частных реестрах Git
• Настройка кэша ресурсов
• Справочник по двоичному кэшу
• Ссылка на кэш ресурсов
• Порты наложения
• режим манифеста
• vcpkg.json
• vcpkg-configuration.json
• Переменные среды конфигурации vcpkg