教程：使用 kmpkg 打包库

本教程将指导你如何使用自定义覆盖端口目录为 kmpkg 打包 C++ 库。建议你在开始前先阅读使用 CMake 安装和使用包教程。

前提条件

终端
C++ 编译器
CMake
Git

cmd-powershell

信息

在 Windows 上，本教程使用 Visual Studio 的 MSVC 作为 C++ 开发编译器。

1 - 安装配置 kmpkg

1. 克隆仓库

第一步是从 GitHub 克隆 kmpkg 仓库。该仓库包含获取 kmpkg 可执行文件的脚本，以及由 kmpkg 社区维护的精选开源库注册表。执行以下命令克隆：

git clone https://github.com/kumose/kmpkg.git

kmpkg 精选注册表包含超过 2000 个开源库，这些库已通过 kmpkg 的持续集成流水线验证，可相互兼容。仓库本身不包含库的源代码，仅存储用于在系统中构建和安装这些库的构建脚本（recipes）和元数据。

2. 运行引导脚本

克隆仓库后，导航到 kmpkg 目录并执行引导脚本：

cmd
powershell
bash

cd kmpkg && bootstrap-kmpkg.bat

cd kmpkg; .\bootstrap-kmpkg.bat

cd kmpkg && ./bootstrap-kmpkg.sh

引导脚本会执行前置检查并下载 kmpkg 可执行文件。

至此，kmpkg 已安装配置完成，可直接使用。

2 - 配置 `KMPKG_ROOT` 环境变量

执行以下命令设置 KMPKG_ROOT 环境变量：

bash
cmd
powershell

export KMPKG_ROOT=/path/to/kmpkg
export PATH=$KMPKG_ROOT:$PATH

使用 export 命令设置的环境变量仅对当前 Shell 会话有效。若需在所有会话中永久生效，需将上述命令添加到 Shell 的配置文件中（例如 ~/.bashrc 或 ~/.zshrc）。

set "KMPKG_ROOT=C:\path\to\kmpkg"
set PATH=%KMPKG_ROOT%;%PATH%

此方式设置的环境变量仅对当前终端会话有效。若需在所有会话中永久生效，需通过 Windows 系统环境变量面板进行设置。

$env:KMPKG_ROOT="C:\path\to\kmpkg"
$env:PATH="$env:KMPKG_ROOT;$env:PATH"

此方式设置的环境变量仅对当前终端会话有效。若需在所有会话中永久生效，需通过 Windows 系统环境变量面板进行设置。

KMPKG_ROOT 用于指定 kmpkg 实例的安装路径，将其添加到 PATH 可确保能从终端直接运行 kmpkg 命令。

3 - 配置自定义覆盖端口目录

在使用 CMake 安装和使用包教程中创建的 "Hello World" 项目旁，新建名为 custom-overlay 的目录。
在 custom-overlay 目录内，创建名为 kmpkg-sample-library 的文件夹。

4 - 配置端口文件

首先，在 custom-overlay/kmpkg-sample-library 文件夹中创建 kmpkg.json 文件，内容如下：

{
  "name": "kmpkg-sample-library",
  "version": "1.0.2",
  "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
    }
  ]
}

kmpkg.json 作为清单文件，定义 C++ 库的元数据和依赖关系，为 kmpkg 提供构建、安装和管理包所需的关键信息：

name：库的名称（用作包标识符）。
version：库的版本号。
homepage：项目主页 URL（通常是代码仓库地址），方便用户了解更多信息或贡献代码。
description：库的简要描述（用于文档和用户参考）。
license：库的分发许可证。
dependencies：库所需的依赖项列表：
- fmt：运行时依赖项，构建和使用包时均需依赖。
- kmpkg-cmake：构建依赖项（host: true 表示仅构建时需要，使用时无需依赖），提供 kmpkg 端口常用的 CMake 函数和宏。
- kmpkg-cmake-config：构建依赖项，用于辅助生成兼容 kmpkg 的 CMake 配置脚本。

有关 kmpkg.json 的更多信息，请参阅清单文件文档。

接下来，在 custom-overlay/kmpkg-sample-library 目录中创建 usage 文件，内容如下：

kmpkg-sample-library 提供以下 CMake 目标：

find_package(my_sample_lib CONFIG REQUIRED)
target_link_libraries(main PRIVATE my_sample_lib::my_sample_lib)

为端口提供使用文档可帮助用户快速集成到项目中。强烈建议在端口目录（ports/<端口名>/usage）中添加 usage 文件，说明与构建系统集成的最小步骤。使用说明应优先遵循上游项目的指导；若上游未提供，需查看其构建系统以确定导出目标的正确使用方式。

有关详细指导，请参阅处理使用文档文件。

最后，在 custom-overlay/kmpkg-sample-library 目录中创建 portfile.cmake 文件，内容如下：

kmpkg_check_linkage(ONLY_STATIC_LIBRARY)

kmpkg_from_github(
    OUT_SOURCE_PATH SOURCE_PATH
    REPO MicrosoftDocs/kmpkg-docs
    REF "${VERSION}"
    SHA512 0 # 临时值，下一节将修改此值
    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")

该端口文件定义了如何通过 kmpkg 从 GitHub 下载、构建、安装和打包特定 C++ 库：

kmpkg_check_linkage(ONLY_STATIC_LIBRARY)：指定该包仅支持静态链接。
kmpkg_from_github：从 GitHub 仓库下载源代码：
- OUT_SOURCE_PATH SOURCE_PATH：指定源代码解压目录。
- REPO MicrosoftDocs/kmpkg-docs：存储源代码的 GitHub 仓库。
- REF "${VERSION}"：要下载的源代码版本。
- SHA512 0：源代码 SHA-512 哈希值的占位符（用于完整性验证）。
- HEAD_REF cmake-sample-lib：仓库的默认分支。
kmpkg_cmake_configure：使用 CMake 配置项目，准备构建。
- SOURCE_PATH "${SOURCE_PATH}"：之前下载的源代码路径。
kmpkg_cmake_install()：使用 CMake 构建并安装包。
kmpkg_cmake_config_fixup(PACKAGE_NAME "my_sample_lib")：修复 CMake 包配置文件，使其兼容 kmpkg。
file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include")：删除调试版本安装目录中的 include 文件夹，避免冲突。
file(INSTALL "${CMAKE_CURRENT_LIST_DIR}/usage" ...)：将使用说明文件复制到包的 share 目录。
kmpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE")：将 LICENSE 文件安装到包的 share 目录，并命名为 copyright。

有关更多信息，请参阅维护者指南。

5 - 更新 `portfile.cmake` 中的 SHA512 值

执行以下命令：

kmpkg install kmpkg-sample-library --overlay-ports=C:\path\to\custom-overlay

运行后会出现较长的错误信息，在输出中查找以下内容：

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

复制实际哈希值 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417，替换 portfile.cmake 中 SHA512 字段的占位值。

重新运行安装命令：

kmpkg install kmpkg-sample-library --overlay-ports=C:\path\to\custom-overlay

成功输出示例：

Computing installation plan...
The following packages will be built and installed:
    kmpkg-sample-library:x64-windows -> 1.0.2 -- C:\Users\dev\demo\custom-overlay\kmpkg-sample-library
Detecting compiler hash for triplet x64-windows...
Restored 0 package(s) from C:\Users\dev\AppData\Local\kmpkg\archives in 174 us. Use --debug to see more details.
Installing 1/1 kmpkg-sample-library:x64-windows...
Building kmpkg-sample-library:x64-windows...
-- Installing port from location: C:\Users\dev\demo\custom-overlay\kmpkg-sample-library
-- Note: kmpkg-sample-library only supports static library linkage. Building static library.
-- Using cached Microsoft-kmpkg-docs-1.0.2.tar.gz.
-- Cleaning sources at C:/Users/dev/demo/kmpkg/buildtrees/kmpkg-sample-library/src/1.0.2-2aff836404.clean. Use --editable to skip cleaning for the packages you specify.
-- Extracting source C:/Users/dev/demo/kmpkg/downloads/Microsoft-kmpkg-docs-1.0.2.tar.gz
-- Using source at C:/Users/dev/demo/kmpkg/buildtrees/kmpkg-sample-library/src/1.0.2-2aff836404.clean
-- Configuring x64-windows
-- Building x64-windows-dbg
-- Building x64-windows-rel
-- Installing: C:/Users/dev/demo/kmpkg/packages/kmpkg-sample-library_x64-windows/share/kmpkg-sample-library/usage
-- Installing: C:/Users/dev/demo/kmpkg/packages/kmpkg-sample-library_x64-windows/share/kmpkg-sample-library/copyright
-- Performing post-build validation
Stored binaries in 1 destinations in 94 ms.
Elapsed time to handle kmpkg-sample-library:x64-windows: 6.1 s
Total install time: 6.1 s
kmpkg-sample-library provides CMake targets:

find_package(my_sample_lib CONFIG REQUIRED)
target_link_libraries(main PRIVATE my_sample_lib::my_sample_lib)

6 - 验证端口构建

为验证库是否能正常构建和链接，需在安装包教程中创建的 helloworld 项目中添加新依赖。修改项目的清单文件和配置文件如下：

步骤 1：修改 `helloworld/kmpkg.json`

添加 kmpkg-sample-library 依赖：

{
    "dependencies": [
        "fmt",
        "kmpkg-sample-library"
    ]
}

步骤 2：修改 `helloworld/kmpkg-configuration.json`

添加包含新端口的 overlay-ports 目录：

{
  "default-registry": {
    "kind": "git",
    "baseline": "45f6e57d3e10ad96b7db206cf7888f736ba5aa61",
    "repository": "https://github.com/kumose/kmpkg"
  },
  "registries": [
    {
      "kind": "artifact",
      "location": "https://github.com/kumose/kmpkg-ce-catalog/archive/refs/heads/main.zip",
      "name": "microsoft"
    }
  ],
  "overlay-ports": [
    "../custom-overlay"
  ]
}

步骤 3：修改 `helloworld/CMakeLists.txt` 和 `helloworld/main.cpp`

更新 CMake 配置文件以使用新依赖：

cmake_minimum_required(VERSION 3.10)

project(HelloWorld)

find_package(fmt CONFIG REQUIRED)
find_package(my_sample_lib CONFIG REQUIRED)  # 添加此行

add_executable(HelloWorld helloworld.cpp)

target_link_libraries(HelloWorld PRIVATE fmt::fmt)
target_link_libraries(HelloWorld PRIVATE my_sample_lib::my_sample_lib)  # 添加此行

更新主程序代码：

#include "my_sample_lib.h"  // 替换 #include <fmt/core.h>

int main()
{
    greet("kmpkg!");  // 替换 fmt::print("Hello World!\n)
    return 0;
}

步骤 4：配置、构建并运行应用

使用 CMake 配置构建：

cmake --preset=default

构建项目：

cmake --build build

运行应用：

./build/HelloWorld

可执行文件路径可能因系统而异（例如 Windows 上为 ./build/Debug/HelloWorld.exe）。

成功运行后输出：

Hello kmpkg!

后续步骤

已将 kmpkg-sample-library 打包为 kmpkg 端口，下一步可将其添加到 kmpkg 精选注册表。请参阅向 kmpkg 注册表添加端口。

有关更多信息，请参阅：

前提条件​

1 - 安装配置 kmpkg​

1. 克隆仓库​

2. 运行引导脚本​

2 - 配置 KMPKG_ROOT 环境变量​

3 - 配置自定义覆盖端口目录​

4 - 配置端口文件​

5 - 更新 portfile.cmake 中的 SHA512 值​

6 - 验证端口构建​

步骤 1：修改 helloworld/kmpkg.json​

步骤 2：修改 helloworld/kmpkg-configuration.json​

步骤 3：修改 helloworld/CMakeLists.txt 和 helloworld/main.cpp​

步骤 4：配置、构建并运行应用​

后续步骤​