【鸿蒙PC三方库移植适配框架解读系列】第四篇：构建执行、产物获取与 HAP 集成

系列导读：本文是 Lycium 适配系列的第四篇，介绍 HPKBUILD 编写完成后如何执行构建、分析构建日志、处理多依赖递归编译、获取产物并进行 HAP 集成。

欢迎加入【开源鸿蒙PC社区】，一起共建鸿蒙化C/C++三方库生态。

前言

系列索引

1. 构建执行

1.1 启动构建

HPKBUILD 编写完成后，执行构建命令：

cd lycium
./build.sh mylib

框架将自动完成以下工作：

1. 加载交叉编译环境（envset.sh）
2. 解析依赖关系
3. 下载源码、校验完整性、解压
4. 为每个架构循环执行 prepare() → build() → package()
5. 记录构建结果

1.2 构建流程全解析

build_hpk.sh 中 builpackage() 函数的完整执行序列：

2. 构建日志分析

2.1 日志位置

每个架构生成独立的构建日志。日志文件的默认位置与 HPKBUILD 所在目录对应：

# 如果 HPKBUILD 在 thirdparty/mylib/ 下
thirdparty/mylib/mylib-1.0.0-arm64-v8a-lycium_build.log

# 如果 HPKBUILD 在 community/mylib/ 下
community/mylib/mylib-1.0.0-arm64-v8a-lycium_build.log

格式：<pkgname>-<pkgver>-<arch>-lycium_build.log

同时框架还会在 lycium/script/ 下生成一份日志归档副本，方便集中查看。

2.2 日志内容

日志包含 build() 中通过 >$buildlog 2>&1 重定向的所有输出。典型内容：

# 查看构建日志（快速定位错误）
tail -100 thirdparty/mylib/mylib-1.0.0-arm64-v8a-lycium_build.log

# 搜索报错关键字
grep -i "error\|failed\|undefined reference" thirdparty/mylib/*.log

2.3 常见构建失败排查

2.4 日志调试技巧

# 实时查看构建输出（不等待构建完成）
./build.sh mylib 2>&1 | tee build.log

# 只查看错误行
grep -E "^(.*error:|.*Error |make:.*\*\*\*)" script/mylib-*.log

# 对比不同架构的日志
diff script/mylib-1.0.0-arm64-v8a-lycium_build.log \
     script/mylib-1.0.0-armeabi-v7a-lycium_build.log | less

# 查看构建记录
cat usr/hpk_build.csv

3. 多库递归构建

3.1 依赖传递机制

当构建的库有依赖（depends 非空）时，框架的依赖处理流程：

./build.sh libA
  → builddepends() 读取 libA/depends=("libB")
  → 检查 libB 是否已构建（查 hpk_build.csv）
  → 未构建 → 退出码 101
  → ./build.sh 捕获退出码 101
  → 将 libB 加入 LYCIUM_DEPEND_PKGNAMES
  → ./build.sh libA libB   # 先构建 libB，待就绪后构建 libA
  → 递归直到所有依赖就绪

3.2 手动指定多库构建

# 同时构建多个库
./build.sh libA libB libC

# 先构建依赖库，再构建目标库
./build.sh libB libC libA

3.3 依赖构建的注意事项

1. 依赖顺序不重要：框架会自动按拓扑排序，先构建被依赖的库
2. 共享依赖：多个库依赖同一个库时，只构建一次
3. 循环依赖：A 依赖 B、B 依赖 A 会导致死循环，需要检查依赖设计
4. 架构超集规则：被依赖库的 archs 必须是当前库 archs 的超集

# 正确：libA 依赖 libB，libB 的 archs 覆盖 libA
# libA/HPKBUILD
archs=("arm64-v8a")
depends=("libB")

# libB/HPKBUILD
archs=("armeabi-v7a" "arm64-v8a")  # ✓ 超集，覆盖 arm64-v8a

4. 产物获取

4.1 产物分布

构建完成后，产物分布在以下位置：

4.2 产物验证

# 检查产物结构
ls -la lycium/usr/mylib/arm64-v8a/
# 输出：
# drwxr-xr-x  include/
# drwxr-xr-x  lib/
#   ├── libmylib.so
#   ├── libmylib.a
#   └── pkgconfig/
#       └── mylib.pc

# 查看库文件信息（确认架构正确）
file lycium/usr/mylib/arm64-v8a/lib/libmylib.so
# 输出：ELF 64-bit LSB shared object, ARM aarch64, ...

# 查看导出的符号
llvm-nm -D lycium/usr/mylib/arm64-v8a/lib/libmylib.so | head -20

4.3 产物获取流程

5. HAP 集成

5.1 集成步骤

应用开发者从 usr/ 获取产物后，集成到 HAP 工程：

5.2 CMakeLists.txt 集成示例

# HAP 工程 CMakeLists.txt
cmake_minimum_required(VERSION 3.16)
project(MyApp)

# 指定第三方库路径
set(MYLIB_PATH ${CMAKE_CURRENT_SOURCE_DIR}/libs/mylib)

# 添加头文件搜索路径
include_directories(${MYLIB_PATH}/include)

# 添加库文件搜索路径
link_directories(${MYLIB_PATH}/lib)

# 链接库
add_library(myapp SHARED src/main.cpp)
target_link_libraries(myapp mylib)  # 链接 libmylib.so

更规范的 HAP 集成方式：

# 使用 target_include_directories 和 target_link_libraries
add_library(myapp SHARED src/main.cpp)

# 直接指定绝对路径（开发阶段）
target_include_directories(myapp PRIVATE
    ${CMAKE_CURRENT_SOURCE_DIR}/libs/mylib/arm64-v8a/include
)
target_link_directories(myapp PRIVATE
    ${CMAKE_CURRENT_SOURCE_DIR}/libs/mylib/arm64-v8a/lib
)
target_link_libraries(myapp PRIVATE
    mylib
    c
    log  # OHOS 日志库
)

5.3 HNP 集成

如果库提供了 HNP 包（output/<arch>/<pkgname>.hnp），集成更简单：

1. 将 .hnp 文件放入 HAP 工程的 libs/ 目录
2. 在 build-profile.json5 中配置 native 库路径
3. 构建工具会自动解包 HNP 并链接

5.4 hap_integrate.md 编写建议

作为适配者，为应用开发者提供清晰的集成文档：

# mylib HAP 集成指南

## 产物文件
- libmylib.so（arm64-v8a / armeabi-v7a）
- include/mylib.h

## 集成步骤
1. 将对应架构的 libmylib.so 复制到 `entry/libs/<arch>/`
2. 将 include/mylib.h 复制到 `entry/src/main/cpp/include/`
3. 在 CMakeLists.txt 中添加：
   ```cmake
   target_link_libraries(entry PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/libs/${OHOS_ARCH}/libmylib.so)

API 说明

• mylib_init()
• mylib_process()
• mylib_cleanup()

6. 本机构建（DevBox）

当在 OpenHarmony 设备（DevBox）上直接构建时，使用 build_local.sh：

./build_local.sh mylib

该脚本的特点：

• 自动识别操作系统为 HarmonyOS
• 设置 TARGET_HARMONYOS=true
• 仅构建 arm64-v8a 架构（其他架构自动跳过）
• 产物安装到设备本地系统路径（而不是 usr/ 目录）

下篇预告

了解了构建流程和产物获取后，下一篇将用一张完整的流程图展示适配者、Lycium 框架和 OHOS SDK 三者之间的交互关系，并总结各环节的角色职责。