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

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

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

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

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

  • Настройка двоичного кэша и кэша ресурсов для конвейера Azure DevOps
  • Настройка конвейера для тестирования портов реестра

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

Настройка двоичного кэша и кэша ресурсов для конвейеров Azure DevOps

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

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

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

Пример. Включение кэширования активов и двоичных файлов в конвейере Azure DevOps

steps: 
- task: NuGetAuthenticate@1

- script: $(Build.Repository.LocalPath)/vcpkg/vcpkg install --triplet=x64-windows
  displayName: some vcpkg task
  env:
    X_VCPKG_ASSET_SOURCES: "clear;x-azurl,https://my.domain.com/container,$(VcpkgAssetCache),readwrite"
    VCPKG_BINARY_SOURCES: "clear;nuget,https://my.domain.com/vcpkgBinaryCache/nuget/v3/index.json,readwrite"

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

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

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

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

VCPKG_BINARY_SOURCES — переменная среды, используемая для настройки двоичных кэшей в vcpkg. В этом примере для него задано значение clear;nuget,https://my.domain.com/vcpkgBinaryCache/nuget/v3/index.json,readwrite. Это позволяет серверной части NuGet для двоичного кэша использовать веб-канал NuGet по адресу https://my.domain.com/vcpkgBinaryCache/nuget/v3/index.json. Для проверки подлинности в веб-канале NuGet могут потребоваться некоторые дополнительные действия, см . инструкции по настройке проверки подлинности NuGet с помощью ADO.

Следующая задача должна быть добавлена как в конвейере, чтобы пройти проверку подлинности в веб-каналах NuGet Azure Artifacts. Эта задача также должна выполняться перед любой задачей, включающей vcpkg.

- task: NuGetAuthenticate@1

Если вы используете другой узел для веб-каналов NuGet, ознакомьтесь с документацией по проверке подлинности NuGet.

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

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

После настройки двоичного кэша и кэша ресурсов для среды 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 в конвейере Azure DevOps

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

steps:
- checkout: self
  submodules: true

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

resources:
  repositories:
    - repository: vcpkgRepo
      type: github
      name: Microsoft/vcpkg
      endpoint: MyGitHubServiceConnection

steps:
  - checkout: vcpkgRepo

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

После проверка выхода из репозитория vcpkg в качестве подмодула или клонирования из GitHub необходимо запустить скрипт начальной загрузки vcpkg.

steps:
  - script: vcpkg/bootstrap-vcpkg.sh

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

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

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

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

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

steps:
- script: $(Build.Repository.LocalPath)/vcpkg/vcpkg install
  env:
    X_VCPKG_ASSET_SOURCES: "clear;x-azurl,https://my.domain.com/container,$(VcpkgAssetCache),readwrite"
    VCPKG_BINARY_SOURCES: "clear;nuget,https://my.domain.com/demoBinaries/nuget/v3/index.json,readwrite"
    VCPKG_OVERLAY_PORTS: "$(Build.Repository.LocalPath)/ports"

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

Объединение файлов YAML конвейеров должно выглядеть примерно так:

.azure-pipelines/test-ports.yml

trigger:
- main

pool:
  vmImage: windows-latest

steps:
- checkout: self
  submodules: true

- task: NuGetAuthenticate@1

- script: $(Build.Repository.LocalPath)/vcpkg/bootstrap-vcpkg.bat
  displayName: Bootstrap vcpkg

- script: $(Build.Repository.LocalPath)/vcpkg/vcpkg install --triplet=x64-windows
  env:
    X_VCPKG_ASSET_SOURCES: "clear;x-azurl,https://my.domain.com/container,$(VcpkgAssetCache),readwrite"
    VCPKG_BINARY_SOURCES: "clear;nuget,https://my.domain.com/demoBinaries/nuget/v3/index.json,readwrite"
    VCPKG_OVERLAY_PORTS: "$(Build.Repository.LocalPath)/ports"

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

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

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

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