系列导读：本文是 Lycium 适配系列的第二篇，介绍 Lycium 项目的目录结构，以及如何为新库创建适配目录和相关文件。

---

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

前言

项目	说明
macOS环境配置	https://bxming.blog.csdn.net/article/details/159284830
Ubuntu环境配置（或者windows + wsl）	https://bxming.blog.csdn.net /article/details/159284760
lycium框架	https://atomgit.com/OpenHarmonyPCDeveloper/lycium_plusplus.git
应用平台	HarmonyOS PC

系列索引

篇章	标题	内容
第一篇	概述与环境配置	Lycium 概念、构建机要求、OHOS SDK 配置
第二篇	项目结构与适配目录创建	目录结构、community vs thirdparty、创建适配目录
第三篇	HPKBUILD 编写详解	元数据字段、过程函数、三种构建系统写法
第四篇	构建执行与产物获取	构建流程、日志分析、多库递归、HAP 集成
第五篇	流程图与角色职责	完整流程图、各角色职责、协作时序
第六篇	关键注意事项与最佳实践	依赖管理、架构超集、日志调试、外部适配仓
第七篇	快速参考与模板	入门步骤、模板、完整案例、检查清单

1. Lycium 项目目录结构（适配者视角）

当拿到 Lycium 框架代码后，lycium_plusplus/ 的目录结构如下：

lycium_plusplus/
├── lycium/                              # 框架核心
│   ├── build.sh                         # [入口] 主构建脚本
│   ├── build_local.sh                   # [入口] 鸿蒙本机构建入口
│   ├── script/
│   │   ├── build_hpk.sh                 # [核心] 构建调度引擎
│   │   ├── envset.sh                    # [核心] 交叉编译环境设置
│   │   └── load_outer_parts.py          # 外部适配仓加载
│   ├── template/HPKBUILD                # HPKBUILD 模板
│   ├── usr/                             # 构建产物安装目录
│   │   └── <pkgname>/<arch>/
│   │       ├── include/                 # 头文件
│   │       ├── lib/                     # .so / .a / pkgconfig
│   │       ├── bin/                     # 可执行文件
│   │       └── share/                   # 文档/配置
│   ├── output/                          # 归档 / HNP 产物
│   └── Buildtools/
│       └── README.md                    # 环境配置说明文档
│
├── community/                           # 官方已适配的库（内置）
│   └── <pkgname>/
│       ├── HPKBUILD                     # 构建描述文件（核心）
│       ├── README.OpenSource            # 开源合规声明
│       ├── SHA512SUM                    # 源码压缩包 SHA512 校验值
│       ├── <pkgname>_oh_pkg.patch       # OpenHarmony 适配补丁
│       ├── OAT.xml                      # 开源合规检查配置
│       ├── hnp.json                     # HNP 打包配置
│       └── docs/
│           └── hap_integrate.md         # HAP 工程集成说明
│
├── thirdparty/                          # 新建适配目录（适配者在此放置 HPKBUILD）
├── external_deps/                       # 外部适配仓
│   ├── module.json                      # 外部仓配置清单
│   └── <pkgname>/                       # git clone 的外部适配仓
│       └── HPKBUILD
└── datalog/                             # 构建日志归档

关键目录说明

目录	用途	适配者是否需要关注
lycium/	框架核心脚本、构建产物存放	✅ 构建时需要进入此目录执行命令
community/	官方已适配的库，作为参考范例	✅ 强烈建议参考，尤其是新手
thirdparty/	适配者新建适配的目录	⭐ 核心工作区，新适配都放在这里
external_deps/	从外部 git 仓库拉取的适配代码	可选，用于团队协作共享适配
datalog/	构建日志归档	调试时需要查看

community/ 与 thirdparty/ 的区别

这是新手最容易混淆的概念：

• community/：Lycium 官方维护的、已经验证通过的库适配。只读，不要修改。作为学习范例和依赖回退（当在 thirdparty/ 中找不到依赖时，框架会自动搜索 community/）。
• thirdparty/：适配者的工作区。所有新库的适配文件都放在这里。框架构建时，优先扫描 thirdparty/，再到 community/ 找依赖。

---

2. 阶段 0：环境准备

在开始适配之前，确保以下准备工作已完成（详细步骤参考第一篇）：

步骤	操作	涉及工具/组件
0.1	安装基本编译工具	apt install gcc cmake make ninja-build pkg-config autoconf automake wget
0.2	下载 OHOS SDK 并解压	wget / 浏览器下载
0.3	设置 OHOS_SDK 环境变量	export OHOS_SDK=/path/to/ohos-sdk/linux
0.4	（可选）获取 Lycium 框架代码	git clone 或从 OpenHarmony 源码中获取
0.5	（可选）配置 external_deps/module.json 指定外部适配仓	load_outer_parts.py + module.json

---

3. 阶段 1：创建适配目录与文件

3.1 创建目录

在 thirdparty/ 下为你的库创建目录（以 mylib 为例）：

mkdir -p thirdparty/mylib/docs

3.2 适配目录结构

每个库的适配目录包含以下文件：

thirdparty/mylib/
├── HPKBUILD                 # [必需] 构建描述文件（核心，下篇详解）
├── README.OpenSource        # [必需] 开源合规信息
├── SHA512SUM                # [必需] 源码压缩包校验值
├── mylib_oh_pkg.patch       # [可选] 针对 OH 的源码修改
├── OAT.xml                  # [可选] 开源合规检查配置
├── hnp.json                 # [可选] HNP 打包配置
└── docs/
    └── hap_integrate.md     # [可选] HAP 工程集成指南

3.3 各文件编写指南

HPKBUILD（核心）

这是适配的灵魂文件，用声明式元数据 + 过程式 shell 函数描述如何构建这个库。下一篇文章会详细展开，这里先创建一个最简模板作为占位：

pkgname=mylib
pkgver=1.0.0
pkgrel=0
archs=("armeabi-v7a" "arm64-v8a")
license=("MIT")
depends=()
source="https://example.com/$pkgname-$pkgver.tar.gz"
builddir=$pkgname-$pkgver
packagename=$builddir.tar.gz

prepare() {
    mkdir -p $builddir/$ARCH-build
}

build() {
    cd $builddir
    ${OHOS_SDK}/native/build-tools/cmake/bin/cmake "$@" \
        -DOHOS_ARCH=$ARCH -B$ARCH-build -S./ -L > $buildlog 2>&1
    $MAKE -C $ARCH-build >> $buildlog 2>&1
    ret=$?
    cd $OLDPWD
    return $ret
}

package() {
    cd $builddir
    $MAKE -C $ARCH-build install >> $buildlog 2>&1
    cd $OLDPWD
}

cleanbuild() {
    rm -rf ${PWD}/$builddir
}

README.OpenSource（必需）

JSON 格式，描述库的开源合规信息：

[
    {
        "Name": "mylib",
        "License": "MIT",
        "License File": "LICENSE",
        "Version Number": "1.0.0",
        "Upstream URL": "https://github.com/example/mylib",
        "Description": "A simple example library for OpenHarmony"
    }
]

注意：Description 字段用英文填写，因为合规扫描工具对中文支持有限。

SHA512SUM（必需）

下载源码包后生成：

# 下载源码
wget https://example.com/mylib-1.0.0.tar.gz -O mylib-1.0.0.tar.gz

# 生成校验文件
sha512sum mylib-1.0.0.tar.gz > thirdparty/mylib/SHA512SUM

SHA512SUM 文件内容示例：

a1b2c3d4e5f6...  mylib-1.0.0.tar.gz

注意：checksum() 校验时，会从 SHA512SUM 所在目录查找对应的压缩包文件，确保文件名匹配。

<pkgname>_oh_pkg.patch（可选）

当上游代码无法直接在 OH 上编译时，通过 patch 做适配修改。常见需要 patch 的情况：

场景	示例
CMakeLists.txt 缺少 OH 平台检测	添加 CMAKE_SYSTEM_NAME=OHOS 判断
使用了 non-POSIX API	替换为 POSIX 兼容写法
硬编码了 Linux 路径	改为相对路径或 CMake 变量
依赖了 OH 上不可用的系统库	条件编译排除
内嵌汇编不兼容 ARM64	提供 C 语言 fallback 实现

生成 patch 的标准流程：

# 1. 获取并解压源码
wget https://example.com/mylib-1.0.0.tar.gz
tar xf mylib-1.0.0.tar.gz
cp -r mylib-1.0.0 mylib-1.0.0-orig

# 2. 修改源码...
# vim mylib-1.0.0/CMakeLists.txt

# 3. 生成 patch
diff -uNr mylib-1.0.0-orig mylib-1.0.0 > mylib_oh_pkg.patch

# 4. 放置到适配目录
cp mylib_oh_pkg.patch thirdparty/mylib/

然后在 HPKBUILD 的 prepare() 中应用 patch：

prepare() {
    cd $builddir
    patch -p1 < ${OLDPWD}/../mylib_oh_pkg.patch
    mkdir -p $ARCH-build
    cd $OLDPWD
}

OAT.xml（可选）

开源合规检查工具的配置文件。从 community/ 下找一个同类库的 OAT.xml 复制修改即可，大部分内容可以复用。

hnp.json（可选）

HNP（鸿蒙 Native Package）打包配置。当需要将编译产物打包成 HNP 供 HAP 工程使用时需要此文件。

{
    "libs": [
        {
            "name": "libmylib.so",
            "arch": "arm64-v8a"
        }
    ],
    "headers": "include/",
    "description": "mylib for OpenHarmony"
}

docs/hap_integrate.md（可选）

向应用开发者说明如何在 HAP 工程中集成此库。至少包含：

• 产物有哪些（头文件、动态/静态库）
• 如何在 CMakeLists.txt 中链接
• 如何在代码中 #include
• 如果有多个架构，如何选择

---

4. 参考官方适配的最佳实践

在 community/ 目录下有大量官方已验证通过的适配范例，建议新手先读再写：

# 查看有哪些官方适配
ls community/

# 参考一个与你目标库类型相似的
cat community/cJSON/HPKBUILD
cat community/cJSON/README.OpenSource

选择参考对象的建议：

你的目标库	参考对象	原因
CMake 构建的库	cJSON	典型的 CMake 项目，写法简洁清晰
autotools 构建的库	ncurses	展示了 configure + make 的完整流程
有复杂依赖的库	readline	展示了 depends[] 的配置和依赖传递
需要打 patch 的库	任意有 _oh_pkg.patch 的库	看看 patch 如何组织和应用

---

5. 开源项目模板

对于常见的构建系统（CMake、autotools、纯 Makefile），社区提供了以下通用模板：

5.1 CMake 项目模板

# 通用 CMake 项目模板（推荐）
pkgname="mylib"
pkgver="1.0.0"
pkgrel="0"
archs=("armeabi-v7a" "arm64-v8a")
license=("MIT")
pkgdesc="Description of mylib"
url="https://github.com/example/mylib"
source="https://github.com/example/mylib/archive/refs/tags/v$pkgver.tar.gz"
builddir=$pkgname-$pkgver
buildtools="cmake"
sha512sums=()
depends=()
makedepends=()

prepare() {
    cd $builddir
}

build() {
    cd $builddir
    mkdir -p $ARCH-build
    cd $ARCH-build
    cmake .. $buildargs
    $MAKE
    $MAKE install DESTDIR=$LYCIUM_ROOT/usr/$pkgname/$ARCH/
    cd $OLDPWD
}

cleanbuild() {
    rm -rf ${builddir}/$ARCH-build
}

5.2 configure 项目模板

# autotools 项目模板
pkgname="mylib"
pkgver="1.0.0"
pkgrel="0"
archs=("armeabi-v7a" "arm64-v8a")
license=("GPLv3")
source="https://example.com/mylib-$pkgver.tar.gz"
builddir=$pkgname-$pkgver
buildtools="configure"
sha512sums=()
depends=()

prepare() {
    cd $builddir
    # 如果需要重新生成 configure 脚本
    autoreconf -fi
}

build() {
    cd $builddir
    mkdir -p $ARCH-build
    cd $ARCH-build
    ../configure --prefix=$LYCIUM_ROOT/usr/$pkgname/$ARCH \
        --host=$ARCH-linux-ohos \
        $buildargs
    $MAKE
    $MAKE install
    cd $OLDPWD
}

cleanbuild() {
    rm -rf ${builddir}/$ARCH-build
}

5.3 纯 Makefile 项目模板

# 纯 Makefile 项目模板
pkgname="mylib"
pkgver="1.0.0"
pkgrel="0"
archs=("armeabi-v7a" "arm64-v8a")
license=("BSD-3-Clause")
source="https://example.com/mylib-$pkgver.tar.gz"
builddir=$pkgname-$pkgver
buildtools="make"
sha512sums=()
depends=()

prepare() {
    cd $builddir
}

build() {
    cd $builddir
    # 通过命令行传递变量到 Makefile
    CC=$CC AR=$AR STRIP=$STRIP \
        $MAKE PREFIX=$LYCIUM_ROOT/usr/$pkgname/$ARCH \
        all
    $MAKE PREFIX=$LYCIUM_ROOT/usr/$pkgname/$ARCH install
}

cleanbuild() {
    cd $builddir
    $MAKE clean
}

---

下篇预告

目录和辅助文件创建好了，下一篇进入最核心的部分——编写 HPKBUILD。我们将详解元数据字段的每个参数含义、三种构建系统（CMake / autotools / Makefile）的典型写法、以及 buildargs 和 pkgconfigpath 等框架注入变量的使用技巧。