教程：打包 Azure DevOps 私有依赖项

本教程将引导你为托管在私有 Azure DevOps 代码仓库中的库创建 kmpkg 覆盖端口（overlay port），内容包括身份验证配置、代码上传及覆盖端口打包的全流程。

前提条件：

• 具备 Git 和 kmpkg 的基础使用知识；
• 拥有 Azure DevOps 访问权限（需能创建项目、管理 SSH 密钥）；
• 系统已安装 kmpkg 工具；
• 系统已安装 Git。

步骤 1 - 创建私有项目

（配图说明：pkg_ado_dep/ado-new-private-project.md.png）

1. 登录你的 Azure DevOps 账号；
2. 创建一个新的私有项目（若暂无组织，创建项目时会提示你先创建组织）：
   • 命名项目：选择能体现库用途的有意义名称；
   • 可见性：确保项目设置为“私有（Private）”，以管控访问权限。

（图片占位：<img src={adon}/>）

步骤 2 - 在 Azure DevOps 中配置身份验证

使用 SSH 密钥对实现代码仓库的安全访问。

1. 生成 SSH 密钥对

打开终端/命令提示符，执行以下命令生成密钥：

ssh-keygen -t rsa -b 4096 -C "ADO-RSA" -f /path/to/.ssh/id_rsa_ado

参数说明：

• -t rsa：指定密钥类型为 RSA；
• -b 4096：设置密钥长度为 4096 位（高安全性）；
• -C "ADO-RSA"：为密钥添加标识标签（多密钥场景下便于区分）；
• -f /path/to/.ssh/id_rsa_ado：指定密钥文件路径，私钥保存为 id_rsa_ado，公钥为 id_rsa_ado.pub。

执行后会提示输入密钥密码（可选）：

• 输入密码：为密钥增加额外安全层（每次使用密钥时需验证）；
• 直接回车：跳过密码设置（便捷性优先）。

生成完成后，验证密钥文件是否存在：

ls /path/to/.ssh

2. 将 SSH 公钥添加到 Azure DevOps

（配图说明：pkg_ado_dep/ado-add-public-key-1.png、pkg_ado_dep/ado-add-public-key-2.png）

1. 用文本编辑器打开 id_rsa_ado.pub，复制公钥全部内容；
2. 登录 Azure DevOps，进入 用户设置 > SSH 公钥（User Settings > SSH Public Keys）；
3. 粘贴公钥内容并命名（便于后续管理），完成密钥添加。

（图片占位：<img src={adoa}/>、<img src={adoa2}/>）

3. 将 SSH 私钥加载到 SSH 代理

确保密钥可用于身份验证：

ssh-add /path/to/.ssh/id_rsa_ado

4. 测试 SSH 连接

验证与 Azure DevOps 的连通性：

ssh -T git@ssh.dev.azure.com

成功的话会看到如下提示（表明认证通过，Azure DevOps 不支持 shell 访问属于正常现象）：

remote: Shell access is not supported.
shell request failed on channel 0

步骤 3 - 将库上传到 Azure DevOps 仓库

1. 初始化本地 Git 仓库

导航到你的库源码目录，初始化 Git 仓库：

git init

2. 提交库代码

添加并提交源码到本地仓库：

git add .
git commit -m "Initial commit of the sample library"

3. 关联 Azure DevOps 远程仓库

（配图说明：pkg_ado_dep/ado-get-url.png） 从 Azure DevOps 获取仓库的 SSH 地址，添加为远程仓库：

git remote add origin <你的仓库 SSH 地址>

（图片占位：<img src={adoag}/>）

4. 推送库代码到远程仓库

将本地代码上传到 Azure DevOps：

git push -u origin master:main

步骤 4 - 将库打包为覆盖端口

覆盖端口（Overlay Ports） 允许你在 kmpkg 中使用本地自定义端口。

1. 创建覆盖端口目录

mkdir kmpkg-overlay-ports
cd kmpkg-overlay-ports

2. 配置端口文件

需创建两个核心文件：kmpkg.json（清单文件）和 portfile.cmake（构建脚本）。

注意：以下示例使用占位符，请替换为你的实际信息。

(1) kmpkg.json：定义库的元数据和依赖

该文件是 kmpkg 识别包的清单，包含元数据、依赖等核心信息：

{
    "name": "your-library-name",  // 库名称（作为包唯一标识）
    "version": "1.0.0",           // 库版本号
    "description": "Description of your library.",  // 库功能描述
    "dependencies": []            // 库的依赖项列表（无依赖则为空数组）
}

字段说明：

• name：包的唯一标识符，kmpkg 安装/管理时使用；
• version：库的版本号；
• description：库的简要说明（用于文档和用户参考）；
• dependencies：库依赖的其他 kmpkg 包列表。

更多 kmpkg.json 配置规则，请参考 官方参考文档。

(2) portfile.cmake：定义 kmpkg 构建/安装逻辑

该脚本告诉 kmpkg 如何下载、构建、安装你的库：

# 从 Azure DevOps Git 仓库下载源码
kmpkg_from_git(
    OUT_SOURCE_PATH SOURCE_PATH  # 输出源码目录变量
    URL "git@ssh.dev.azure.com:v3/YourOrg/YourProject/YourRepo"  # 仓库 SSH 地址
    REF "<commit-sha>"  # 库代码的提交哈希值
)

# 用 CMake 配置项目
kmpkg_cmake_configure(SOURCE_PATH "${SOURCE_PATH}")

# 构建并安装包
kmpkg_cmake_install()

# 修复 CMake 配置文件（适配 kmpkg 路径规则）
kmpkg_cmake_config_fixup(PACKAGE_NAME your-library-name)

# 安装许可证文件到包的共享目录
file(INSTALL "${SOURCE_PATH}/LICENSE" DESTINATION "${CURRENT_PACKAGES_DIR}/share/your-library-name")

核心指令说明：

• kmpkg_from_git：从 Git 仓库拉取源码，REF 指定具体提交哈希（保证版本确定性）；
• kmpkg_cmake_configure：调用 CMake 配置构建环境；
• kmpkg_cmake_install：执行构建并安装到 kmpkg 目录；
• kmpkg_cmake_config_fixup：修正 CMake 配置文件路径，确保 find_package 能正常找到包；
• file(INSTALL)：安装许可证文件（开源合规要求）。

获取提交哈希（commit-sha）的方法：

mkdir temp && cd temp
git init
git fetch <你的仓库 SSH 地址> main --depth 1 -n
git rev-parse FETCH_HEAD

更多 portfile.cmake 配置参考：

• 端口核心概念
• 覆盖端口
• kmpkg_from_git 函数
• 端口文件变量
• 三元组（Triplets）

3. 安装自定义端口

回到 kmpkg 主目录，指定覆盖端口路径安装你的库：

kmpkg install your-library-name --overlay-ports=/path/to/kmpkg-overlay-ports

后续步骤

你已成功将私有 Azure DevOps 仓库中的库打包为 kmpkg 覆盖端口。本教程为通用指南，请根据你的库特性、开发环境调整具体配置。