设置 vcpkg 端口的自定义注册表后,可能需要添加 Continuos Integration (CI),以验证是否可以成功生成所有依赖项。
Microsoft/vcpkg 的主要 vcpkg 注册表由 vcpkg 团队使用 Azure DevOps Pipelines 进行测试。 这可确保添加新包或更新现有包不会破坏使用者。
本文介绍如何设置 CI 环境以测试自己的注册表中的 vcpkg 端口。
本文介绍如何为 GitHub Actions 中运行的注册表设置 CI 工作流:
- 为 GitHub Actions 工作流设置二进制缓存和资产缓存
- 设置用于测试注册表端口的工作流
先决条件
- 一个 GitHub 帐户
- vcpkg Git 注册表
- 阅读 二进制缓存 教程
- 阅读 资产缓存 教程
为 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 环境时,以下文章可能对你有用。