通过

在 GitHub Actions 中使用 vcpkg 测试自定义注册表端口

设置 vcpkg 端口的自定义注册表后，可能需要添加 Continuos Integration （CI），以验证是否可以成功生成所有依赖项。

Microsoft/vcpkg 的主要 vcpkg 注册表由 vcpkg 团队使用 Azure DevOps Pipelines 进行测试。 这可确保添加新包或更新现有包不会破坏使用者。

本文介绍如何设置 CI 环境以测试自己的注册表中的 vcpkg 端口。

本文介绍如何为 GitHub Actions 中运行的注册表设置 CI 工作流：

  • 为 GitHub Actions 工作流设置二进制缓存和资产缓存
  • 设置用于测试注册表端口的工作流

先决条件

为 GitHub Actions 工作流设置二进制缓存和资产缓存

在时间和计算能力方面，测试大量端口是一项昂贵的任务。 强烈建议在为端口使用 CI 之前，投资为 GitHub Action 工作流设置二进制缓存和资产缓存。

二进制缓存通过确保在每次 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 Actions 缓存后端。 工作流中需要一个额外的步骤才能成功启用此后端。

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 环境设置二进制缓存和资产缓存后，下一步是设置工作流以测试所有注册表的端口。 可以决定此工作流是按计划运行的，还是由新的提交或拉取请求触发。

主 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参考文章了解详细信息。 并参考Manifest模式文档，以了解它们如何协同工作。

在 GitHub Actions 工作流中获取 vcpkg

接下来，需要获取 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_OVERLAY_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 环境时，以下文章可能对你有用。