注意

本节介绍的功能已从 kmpkg 中移除。 相关文档不再维护。

二进制缓存配置

配置语法

二进制缓存通过环境变量 KMPKG_BINARY_SOURCES（值格式为 <源>;<源>;...）和 命令行选项 --binarysource=<源> 进行配置。配置优先级为：先读取环境变量，后读取命令行选项。若需完全禁用二进制缓存，可在命令行末尾添加 --binarysource=clear。

格式	描述
clear	禁用所有先前配置的源（包括默认源）
default[,<rw>]	添加默认的 文件 提供程序
files,<绝对路径>[,<rw>]	添加基于文件系统的存储位置
nuget,<uri>[,<rw>]	添加基于 NuGet 的源；等效于 NuGet CLI 的 -Source 参数
nugetconfig,<路径>[,<rw>]	添加基于 NuGet 配置文件的源；等效于 NuGet CLI 的 -Config 参数
nugettimeout,<秒数>	指定 NuGet 网络操作的超时时间；等效于 NuGet CLI 的 -Timeout 参数
http,<url模板>[,<rw>[,<请求头>]]	添加自定义 HTTP 基于的存储位置
x-azblob,<基础uri>,<sas>[,<rw>]	实验性功能：可能会无预警变更或移除 通过共享访问签名（Shared Access Signature）添加 Azure Blob 存储源
x-azcopy,<基础uri>,[,<rw>]	实验性功能：可能会无预警变更或移除 添加 Azure Blob 存储源，支持 Microsoft Entra ID，依赖 AzCopy 工具
x-azcopy-sas,<基础uri>,<sas>[,<rw>]	实验性功能：可能会无预警变更或移除 通过共享访问签名添加 Azure Blob 存储源，依赖 AzCopy 工具
x-gcs,<前缀>[,<rw>]	实验性功能：可能会无预警变更或移除 添加 Google Cloud Storage (GCS) 源
x-aws,<前缀>[,<rw>]	实验性功能：可能会无预警变更或移除 添加 AWS S3 源
x-aws-config,<参数>	实验性功能：可能会无预警变更或移除 配置所有 AWS S3 提供程序
x-cos,<前缀>[,<rw>]	实验性功能：可能会无预警变更或移除 添加腾讯云对象存储（COS）源
x-gha,<rw>]	已移除：此功能已从 kmpkg 中删除
x-az-universal,<组织>,<项目>,<源>[,<rw>]	实验性功能：可能会无预警变更或移除 使用 Azure Artifacts 中的通用包作为源
interactive	启用 NuGet 的交互式凭据管理（用于调试；需在命令行添加 --debug）

部分源支持的可选参数 <rw> 用于控制访问权限：

• read：仅用于下载二进制文件（默认）
• write：仅用于上传构建生成的二进制文件
• readwrite：同时支持读写

提供程序

AWS S3 提供程序

本节介绍的是 kmpkg 的实验性功能，可能会无预警变更或移除。

x-aws,<前缀>[,<rw>]

通过 AWS CLI 添加 AWS S3 源。<前缀> 必须以 s3:// 开头、以 / 结尾。

x-aws-config,no-sign-request

向 AWS CLI 传递 --no-sign-request 参数。

Azure Blob 存储提供程序

本节介绍的是 kmpkg 的实验性功能，可能会无预警变更或移除。

x-azblob,<基础uri>,<sas>[,<rw>]

通过共享访问签名（SAS）验证添加 Azure Blob 存储提供程序。<基础uri> 需包含容器路径。

腾讯云对象存储提供程序

本节介绍的是 kmpkg 的实验性功能，可能会无预警变更或移除。

x-cos,<前缀>[,<rw>]

添加 COS 源。<前缀> 必须以 cos:// 开头、以 / 结尾。

文件提供程序

files,<绝对路径>[,<rw>]

根据 二进制缓存 ID，将 zip 压缩包存储在指定路径下。

Google Cloud Storage 提供程序

本节介绍的是 kmpkg 的实验性功能，可能会无预警变更或移除。

x-gcs,<前缀>[,<rw>]

添加 Google Cloud Storage 提供程序。<前缀> 必须以 gs:// 开头、以 / 结尾。

快速入门

首先，需创建 Google Cloud Platform 账户和存储桶，参考 GCS 快速入门。

完成快速入门后，已配置 gsutil 命令行工具用于 Google Cloud 身份验证。kmpkg 会依赖该工具，需确保其在系统环境变量 PATH 中。

示例 1（使用无对象通用前缀的存储桶）：

x-gcs,gs://<存储桶名称>/,readwrite

示例 2（使用带对象前缀的存储桶）：

x-gcs,gs://<存储桶名称>/my-kmpkg-cache/maybe/with/many/slashes/,readwrite
x-gcs,gs://<存储桶名称>/my-kmpkg-cache/maybe/with`,commas/too!/,readwrite

逗号（,）可作为 GCS 中对象前缀的一部分。如上述示例所示，需在 kmpkg 配置中对逗号进行转义。GCS 本身不支持文件夹（部分 GCS 工具模拟文件夹功能），无需手动创建或操作 kmpkg 缓存使用的前缀。

GitHub Actions 缓存

注意

本节介绍的功能已从 kmpkg 中移除。 相关文档不再维护。

Azure Artifacts 中的通用包

本节介绍的是 kmpkg 的实验性功能，可能会无预警变更或移除。

注意

x-az-universal 提供程序在处理大量二进制包时性能较慢。kmpkg 团队建议尽可能使用 x-azcopy 等其他后端。

x-az-universal,<组织>,<项目>,<源>[,<rw>]

HTTP 提供程序

http,<url模板>[,<rw>[,<请求头>]]

二进制缓存操作映射到对应的 HTTP 方法：

• 下载 - GET
• 上传 - PUT
• 检查存在性 - HEAD

URL 模板

模板使用大括号 {} 进行变量替换，支持变量：name（包名）、version（版本）、sha（哈希值）、triplet（三元组）。示例：

https://cache.example.com/{name}/{version}/{sha}

请求头

注意

该值可能会出现在外部进程调用的命令行中，在你的环境中可能存在安全风险。

通过指定 HTTP 授权头 支持身份验证。示例：

http,https://cache.example.com/{name}/{version}/{sha},readwrite,Authorization: Bearer BearerTokenValue

NuGet 提供程序

通过 NuGet CLI 的 -Source 参数添加 NuGet 服务器：

nuget,<uri>[,<rw>]

通过 NuGet CLI 的 -Config 参数使用 NuGet 配置文件：

nugetconfig,<路径>[,<rw>]

配置 NuGet 源的超时时间：

nugettimeout,<秒数>

配置文件必须定义 defaultPushSource，才能支持向源推送包。

凭据

许多 NuGet 服务器需要额外凭据才能访问。最灵活的方式是通过 nugetconfig 源指定自定义 nuget.config 文件。详细信息参考「从需要身份验证的源消费包」。

此外，也可通过 NuGet 内置凭据提供程序或自定义环境默认 nuget.config 进行身份验证。可通过以下 NuGet 客户端命令扩展默认配置：

nuget sources add -Name MyRemote -Source https://... -Username $user -Password $pass

然后通过 nuget,MyRemote,readwrite 传递给 kmpkg。可通过 kmpkg fetch nuget 获取 kmpkg 使用的 NuGet 可执行文件路径，示例输出：

$ kmpkg fetch nuget
/kmpkg/downloads/tools/nuget-5.5.1-linux/nuget.exe

非 Windows 用户需通过 mono 运行：mono /path/to/nuget.exe sources add ...。

metadata.repository

nuget 和 nugetconfig 源提供程序在生成 NuGet 包时，会读取特定环境变量填充 metadata.repository 字段：

• 若定义并非空环境变量 KMPKG_NUGET_REPOSITORY，则生成：

  <repository type="git" url="${KMPKG_NUGET_REPOSITORY}"/>

• 若定义并非空 GitHub 相关环境变量（GITHUB_SERVER_URL、GITHUB_REPOSITORY、GITHUB_REF、GITHUB_SHA），则生成：

  <repository type="git"
              url="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}.git"
              branch="${GITHUB_REF}"
              commit="${GITHUB_SHA}"/>

该字段用于将 GitHub Packages 中的包与构建项目关联，而非原始包源。

NuGet 缓存

默认不使用 NuGet 的用户级缓存。若需为所有基于 NuGet 的源启用该缓存，可设置环境变量 KMPKG_USE_NUGET_CACHE 为 true（不区分大小写）或 1。

提供程序示例

若以下未列出你使用的 CI 系统，欢迎提交 PR 补充！

GitHub Packages

推荐使用 NuGet 提供程序 将 kmpkg 与 GitHub Packages 结合使用。

信息

2020-09-21：GitHub 托管代理预装的 kmpkg 版本较旧，不支持最新的二进制缓存功能。直接调用 bootstrap-kmpkg 或 kmpkg 可能会执行非预期的实例。若需使用自定义 kmpkg 副本，需执行以下两步避免问题：

1. 使用 shell: 'bash' 运行等效于 rm -rf "$KMPKG_INSTALLATION_ROOT" 的命令。
2. 始终带路径前缀调用 kmpkg 和 bootstrap-kmpkg，例如 ./kmpkg、kmpkg/kmpkg、.\bootstrap-kmpkg.bat 等。

# actions.yaml
#
# 本示例中，kmpkg 已作为子模块添加（`git submodule add https://github.com/kumose/kmpkg`）。
env:
  KMPKG_BINARY_SOURCES: 'clear;nuget,GitHub,readwrite'

matrix:
  os: ['windows-2019', 'ubuntu-20.04']
  include:
    - os: 'windows-2019'
      triplet: 'x86-windows'
      mono: ''
    - os: 'ubuntu-20.04'
      triplet: 'x64-linux'
      # 非 Windows 平台运行 `nuget.exe` 需依赖 `mono`
      mono: 'mono'

steps:
  # 此步骤假设 kmpkg 已完成引导（运行 `./kmpkg/bootstrap-kmpkg`）
  - name: '配置 NuGet 凭据'
    shell: 'bash'
    # 将 <OWNER> 替换为你的组织名称
    run: |
      ${{ matrix.mono }} `./kmpkg/kmpkg fetch nuget | tail -n 1` \
        sources add \
        -source "https://nuget.pkg.github.com/<OWNER>/index.json" \
        -storepasswordincleartext \
        -name "GitHub" \
        -username "<OWNER>" \
        -password "${{ secrets.GITHUB_TOKEN }}"
      ${{ matrix.mono }} `./kmpkg/kmpkg fetch nuget | tail -n 1` \
        setapikey "${{ secrets.GITHUB_TOKEN }}" \
        -source "https://nuget.pkg.github.com/<OWNER>/index.json"

  # 若使用清单文件，可省略此步骤
  - name: 'kmpkg 包还原'
    shell: 'bash'
    run: >
      ./kmpkg/kmpkg install sqlite3 cpprestsdk --triplet ${{ matrix.triplet }}

若使用 清单文件，可省略 kmpkg 包还原 步骤：构建过程中会自动执行包还原。

更多信息参考 GitHub Packages 的 NuGet 文档。

从流水线使用源

# azure-pipelines.yaml
variables:
- name: KMPKG_BINARY_SOURCES
  value: 'clear;nuget,<源URL>,readwrite'

steps:
# 需添加此任务，允许 kmpkg 通过 NuGet 上传归档文件
- task: NuGetAuthenticate@0

若使用非 Windows 系统的自定义代理，需安装 Mono 以运行 nuget.exe（如 apt install mono-complete、brew install mono 等）。

本地使用源

# Windows Powershell
PS> & $(kmpkg fetch nuget | select -last 1) sources add `
  -name ADO `
  -Source https://pkgs.dev.azure.com/$ORG/_packaging/$FEEDNAME/nuget/v3/index.json `
  -Username $USERNAME `
  -Password $PAT
PS> $env:KMPKG_BINARY_SOURCES="nuget,ADO,readwrite"

# Linux 或 macOS
$ mono `kmpkg fetch nuget | tail -n1` sources add \
  -name ADO \
  -Source https://pkgs.dev.azure.com/$ORG/_packaging/$FEEDNAME/nuget/v3/index.json \
  -Username $USERNAME \
  -Password $PAT
$ export KMPKG_BINARY_SOURCES="nuget,ADO,readwrite"

建议使用个人访问令牌（PAT）作为密码以确保安全性。可在「用户设置」->「个人访问令牌」或 https://dev.azure.com/<ORG>/_usersSettings/tokens 生成 PAT。

ABI 哈希

信息

ABI 哈希相关信息仅作为实现说明，可能会无预警变更。

kmpkg 为每个构建计算一个ABI 哈希（应用程序二进制接口哈希）以确定构建等效性。若两个构建的 ABI 哈希相同，kmpkg 会认为它们完全一致，可跨项目、跨机器复用二进制文件。

ABI 哈希包含以下因素：

• 端口目录中的所有文件
• 三元组文件的内容和名称
• C++ 编译器可执行文件
• C 编译器可执行文件
• 选中的 功能集
• 每个依赖项的 ABI 哈希
• portfile.cmake 引用的所有辅助函数（启发式判断）
• 使用的 CMake 版本
• 使用的 PowerShell 版本（Windows）
• KMPKG_ENV_PASSTHROUGH 中列出的所有环境变量的内容
• 工具链文件的文本内容（KMPKG_CHAINLOAD_TOOLCHAIN_FILE）
• GRDK 工具包（仅当目标平台为 Xbox 时）

尽管包含上述大量因素，仍可能存在破坏缓存一致性或引入非确定性的情况。若你的环境需要跟踪额外信息，可在三元组文件的注释中添加相关内容——这些信息会被纳入 ABI 哈希计算，确保二进制文件的唯一性。

.DS_Store 文件不会纳入 ABI 哈希计算。

计算出的 ABI 哈希会存储在每个包中，同时在当前安装目录的 /share/<port>/kmpkg_abi_info.txt 中保留，供查看验证。

zlib 的 ABI 哈希示例

启用 调试输出 可打印包的完整 ABI 哈希。以 zlib 为例：

[DEBUG] 尝试计算 <路径>\buildtrees\zlib\x86-windows.kmpkg_abi_info.txt 的哈希
[DEBUG] <路径>\buildtrees\zlib\x86-windows.kmpkg_abi_info.txt 的哈希为 bb1c96759ac96102b4b18215db138daedd3eb16c2cd3302ae7bffab2b643eb87

zlib 包的 ABI 哈希 bb1c96759ac96102b4b18215db138daedd3eb16c2cd3302ae7bffab2b643eb87，由所有区分二进制包的相关信息哈希计算得出。

编译器版本是 ABI 哈希的一部分，计算示例如下：

[DEBUG] -- C 编译器标识为 MSVC 19.36.32538.0
[DEBUG] -- CXX 编译器标识为 MSVC 19.36.32538.0
[DEBUG] #COMPILER_HASH#f5d02a6542664cfbd4a38db478133cbb1a18f315

相关文件、编译器和工具版本信息会被哈希计算，最终生成 ABI 哈希：

[DEBUG] <zlib:x86-windows 的 ABI 条目>
[DEBUG]   0001-Prevent-invalid-inclusions-when-HAVE_-is-set-to-0.patch|750b9542cb55e6328cca01d3ca997f1373b9530afa95e04213168676936e7bfa
[DEBUG]   0002-skip-building-examples.patch|835ddecfed752e0f49be9b0f8ff7ba76541cb0a150044327316e22ca84f8d0c2
[DEBUG]   0003-build-static-or-shared-not-both.patch|d6026271dcb3d8fc74b41e235620ae31576a798e77aa411c3af8cd9e948c02b1
[DEBUG]   0004-android-and-mingw-fixes.patch|37a43eddbcb1b7dde49e7659ae895dfd0ff1df66666c1371ba7d5bfc49d8b438
[DEBUG]   cmake|3.26.2
[DEBUG]   features|core
[DEBUG]   portfile.cmake|ac63047b644fa758860dd7ba48ff9a13b058c6f240b8e8d675b8fbba035976be
[DEBUG]   ports.cmake|5a8e00cedff0c898b1f90f7d129329d0288801bc9056562b039698caf31ff3f3
[DEBUG]   post_build_checks|2
[DEBUG]   powershell|7.3.6
[DEBUG]   triplet|x86-windows
[DEBUG]   triplet_abi|3e71dd1d4afa622894ae367adbbb1ecbd42c57c51428a86b675fa1c8cad3a581-36b818778ba6f2c16962495caedb9a7b221d5be4c60de1cd3060f549319a9931-f5d02a6542664cfbd4a38db478133cbb1a18f315
[DEBUG]   usage|be22662327df993eebc437495add75acb365ab18d37c7e5de735d4ea4f5d3083
[DEBUG]   kmpkg-cmake|1b3dac4b9b0bcbef227c954b495174863feebe3900b2a6bdef0cd1cf04ca1213
[DEBUG]   kmpkg-cmake-wrapper.cmake|5d49ef2ee6448479c2aad0e5f732e2676eaba0411860f9bebabe6002d66f57d1
[DEBUG]   kmpkg.json|bc94e2540efabe36130a806381a001c57194e7de67454ab7ff1e30aa15e6ce23
[DEBUG]   kmpkg_copy_pdbs|d57e4f196c82dc562a9968c6155073094513c31e2de475694143d3aa47954b1c
[DEBUG]   kmpkg_fixup_pkgconfig|588d833ff057d3ca99c14616c7ecfb5948b5e2a9e4fc02517dceb8b803473457
[DEBUG]   kmpkg_from_git|8f27bff0d01c6d15a3e691758df52bfbb0b1b929da45c4ebba02ef76b54b1881
[DEBUG]   kmpkg_from_github|b743742296a114ea1b18ae99672e02f142c4eb2bef7f57d36c038bedbfb0502f
[DEBUG]   kmpkg_replace_string|d43c8699ce27e25d47367c970d1c546f6bc36b6df8fb0be0c3986eb5830bd4f1
[DEBUG] </abientries>

信息

triplet_abi 条目包含三个哈希值：x86-windows 三元组文件内容的哈希、windows.cmake 工具链的哈希、编译器哈希。若切换目标平台，这些哈希值会相应变化。