跳到主要内容

教程：更新现有 kmpkg 依赖项版本

本教程将指导你更新现有 kmpkg 依赖项的版本。建议你先阅读 发布库教程，再继续本教程的学习。

通过本教程，你将学会：

前提条件​

  • 终端/命令行工具
  • 已安装 kmpkg
  • 已安装 Git
  • 已安装 C++ 编译器
  • 已完成 打包教程

1 - 创建覆盖端口​

更新现有包的第一步是为目标包创建 覆盖端口（Overlay Port）。

步骤 1：创建存储覆盖端口的目录​

覆盖端口目录可创建在文件系统的任意位置。在本教程的所有步骤中，请将 $OVERLAY_LOCATION 替换为你选定的目录路径。

mkdir "$OVERLAY_LOCATION"

步骤 2：将目标端口内容复制到覆盖端口目录​

本教程以更新 kmpkg-sample-library 端口为例（该端口来自 发布包教程），将其升级为支持动态库的版本。

Copy-Item -Path <path/to/kmpkg-sample-library> -Destination "$OVERLAY_LOCATION" -Recurse

2 - 修改端口版本信息​

将 kmpkg.json 中的版本号修改为 1.0.1：

kmpkg.json

{
  "name": "kmpkg-sample-library",
  "version": "1.0.1",
  "description": "一个示例 C++ 库，用作 kmpkg 打包教程的基础示例。",
  "homepage": "https://github.com/MicrosoftDocs/kmpkg-docs/tree/cmake-sample-lib",
  "license": "MIT",
  "dependencies": [
    "fmt",
    {
      "name": "kmpkg-cmake",
      "host": true
    },
    {
      "name": "kmpkg-cmake-config",
      "host": true
    }
  ]
}

3 - 修改 portfile.cmake​

步骤 1：更新源码引用​

kmpkg 通常通过 kmpkg_from_... 系列维护者函数拉取源码，源码版本由 REF（Git 标签/提交）或 URLS（下载地址）等参数指定。

若这些参数的值未通过 ${VERSION}（清单中的版本变量）推导，需手动更新为实际的 Git 标签、Git 提交哈希或下载 URL。

步骤 2：获取包的 SHA512 哈希值​

执行以下命令安装覆盖端口，此时会触发 SHA512 校验错误，复制错误信息中的“实际哈希值”备用：

kmpkg install --overlay-ports=$OVERLAY_LOCATION kmpkg-sample-library

示例错误输出：

Downloading https://github.com/MicrosoftDocs/kmpkg-docs/archive/1.0.1.tar.gz -> MicrosoftDocs-kmpkg-docs-1.0.1.tar.gz
Successfully downloaded MicrosoftDocs-kmpkg-docs-1.0.1.tar.gz
error: failing download because the expected SHA512 was all zeros, please change the expected SHA512 to: fc55ce73b9175bdfedd73d9df1e7ed744de7ee3fd4aa51cafce65ee7bd49e56dc68301843c31d2ba017fd362663c25f53bbf56cfd35dbac09520e39b86bc25b8

步骤 3：修改 portfile.cmake​

将包的 SHA512 哈希值更新为上述实际值，并移除 ONLY_STATIC_LIBRARY 限制（新版本 kmpkg-sample-library 已支持动态库构建）。

最终的 portfile.cmake 应如下所示：

portfile.cmake

kmpkg_from_github(
    OUT_SOURCE_PATH SOURCE_PATH
    REPO MicrosoftDocs/kmpkg-docs
    REF 1.0.1
    SHA512 fc55ce73b9175bdfedd73d9df1e7ed744de7ee3fd4aa51cafce65ee7bd49e56dc68301843c31d2ba017fd362663c25f53bbf56cfd35dbac09520e39b86bc25b8
    HEAD_REF cmake-sample-lib
)

kmpkg_cmake_configure(
    SOURCE_PATH "${SOURCE_PATH}"
)

kmpkg_cmake_install()

kmpkg_cmake_config_fixup(PACKAGE_NAME "my_sample_lib")

file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include")

file(INSTALL "${CMAKE_CURRENT_LIST_DIR}/usage" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}")
kmpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE")

4 - 安装覆盖端口​

执行以下命令验证端口是否可正常构建：

kmpkg install "--overlay-ports=$OVERLAY_LOCATION" kmpkg-sample-library

5 - 更新内置注册表端口​

步骤 1：替换端口内容​

将 kmpkg 仓库 ports 目录下 kmpkg-sample-library 的内容替换为你更新后的文件，然后在本地 kmpkg 仓库克隆目录中执行以下命令提交变更：

git checkout -b kmpkg-sample-library-1.0.1
git add ports/kmpkg-sample-library

步骤 2：更新版本数据库​

执行 [kmpkg x-add-version] 命令更新版本数据库文件：

kmpkg x-add-version kmpkg-sample-library

步骤 3：推送变更到 Fork 仓库​

执行以下命令提交版本数据库变更，并推送到你 Fork 的 https://github.com/kumose/kmpkg 仓库：

git add versions/.
git commit -m "Update kmpkg-sample-library to version 1.0.1"
git push --set-upstream <fork remote> kmpkg-sample-library-1.0.1

6 - 提交拉取请求（Pull Request）​

  1. 打开 GitHub 并导航到你 Fork 的 kmpkg 仓库；
  2. 点击“Compare & pull request”（对比并创建拉取请求）按钮：
    1. 验证你的变更内容；
    2. 添加描述性的标题和备注；
    3. 填写 PR 审核清单；
  3. 点击“Create pull request”（创建拉取请求）。

至此，你已成功更新 kmpkg 官方精选注册表中的端口！

参考链接​

如需更多信息，请参考：