OpenHarmony 通用三方库适配教程

本文详细介绍如何将已有的C/C++三方库适配到OpenHarmony平台，通过交叉编译生成可在鸿蒙设备上运行的产物。

前言

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

什么是C库适配？

简单来说，C库适配就是让那些已有的C/C++三方库能够在OpenHarmony（鸿蒙）平台上正常运行。我们知道，编写C代码后需要经过编译构建才能运行，而适配的工作就是完成这个"交叉编译"过程——在Windows/Linux开发机上编译出能在鸿蒙设备（ARM架构）上运行的产物。

适配流程概览

整个适配流程分为以下步骤：

虚拟机搭建 → 克隆tpc_c_cplusplus仓库 → 检查并配置编译环境 → 下载OpenHarmony SDK → 选择要适配的三方库并编写编译配置文件 → 编译三方库

---

步骤 1：虚拟机搭建

首先需要搭建Linux开发环境，推荐使用虚拟机运行Ubuntu。

1.1 启用虚拟功能

以管理员身份打开powershell，运行以下命令

启用适用于 Linux 的 Windows 子系统

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

启用虚拟机平台功能（为WSL2所需）

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

1.2 下载 Linux 内核更新程序包

下载适用于 WSL 2 的 Linux 内核更新程序包。下载地址如下:

安装地址

下载完成后，运行安装程序并按照提示完成安装。

1.3 Ubuntu24 安装

打开微软应用商店，搜索“Ubuntu”，在列表中选择ubuntu并安装

安装完成后，可以在开始菜单中找到“Ubuntu 24.04 LTS”，点击它启动终端。

---

步骤 2：克隆tpc_c_cplusplus仓库获取lycium交叉编译框架

tpc_c_cplusplus是OpenHarmony官方维护的C/C++第三方库适配仓库，该仓库主要用于存放已经适配OpenHarmony的C/C++三方库的适配脚本和OpenHarmony三方库适配指导文档、三方库适配相关的工具。

lycium是一款协助开发者通过shell语言实现C/C++三方库快速交叉编译，并在OpenHarmony系统上快速验证的编译框架工具。开发者只需要设置对应C/C++三方库的编译方式以及编译参数，通过lycium就能快速的构建出能在OpenHarmony系统运行的二进制文件。

2.1 进入虚拟机并选择工作目录

打开ubuntu，选择一个合适的目录，创建openharmony文件夹,在该文件夹下克隆仓库

mkdir -p ~/openharmony
cd ~/openharmony

2.2 克隆仓库

在目录下运行下面的命令等待下载完成

git clone https://atomgit.com/openharmony-sig/tpc_c_cplusplus.git

2.3 查看仓库结构

克隆完成后，查看仓库中的内容：

cd tpc_c_cplusplus
tree -L 1

cd lycium/
tree -L 2

---

步骤 3：检查并配置编译环境

这是适配过程中最关键的步骤之一。

在终端执行下面的命令，社区为我们提供了检查环境的脚本，我们克隆然后运行即可

git clone https://atomgit.com/oh-tpc/oh-scripts.git

克隆交叉编译环境配置脚本工程，在oh-scripts/linux目录下执行python3 check_env.py检查编译环境是否包含以下几个基本编译命令： gcc、cmake、make、pkg-config、autoconf、autoreconf、 automake。

3.1 克隆交叉编译环境配置脚本工程

在目录下运行下面的命令把脚本克隆下来

git clone https://atomgit.com/oh-tpc/oh-scripts.git

3.2 运行检查环境的脚本

进入脚本目录，然后运行

cd oh-scripts
cd linux/
python3 check_env.py

缺少什么库就相对应去下载什么库,具体如何在虚拟机环境里面下载所需要的库可以向AI寻求帮助

---

步骤 4：下载OpenHarmony SDK

4.1 获取OpenHarmony SDK下载链接

可以从OpenHarmony SDK 官方发布渠道文档中下载

下面是通过OpenHarmony SDK 官方发布渠道复制链接的

4.2 执行下载脚本

社区为我们提供了一键下载和自动解压OpenHarmony SDK文件，克隆然后运行就可以配置好OpenHarmony环境，脚本默认使用第一种方式的SDK链接地址就是官方渠道，开发者也可以在执行命令后，根据提示输入获取的SDK链接地址。

在oh-scripts/linux目录下执行python3 download_ohsdk.py命令下载OpenHarmony SDK。

python3 download_ohsdk.py

4.3 使环境变量生效

完成后，还需要执行source ~/.bashrc使配置的环境变量生效。

---

步骤 5：在IDE里面打开tpc_c_cplusplus文件夹

打开文件夹

步骤 6：寻找要适配的库(cJSON),编写HPKBUILD文件

6.1 编译配置模板文件HPKBUILD简介

lycium框架为开发者提供了对C/C++目标三方库的编译配置模板文件HPKBUILD

文件所在位置是tpc_c_cplusplus/lycium/template/HPKBUILD,这是一个模板,根据这个模板来写然后进行运行，就可以把三方库编译成能在鸿蒙平台运行的文件，这些文件就是我们的目标产物，这个过程就是交叉编译三方库

6.2 在thirdparty目录下新建目标三方库目录，然后在该目录下新建一个HPKBUILD文件

我这里以cJSON为例子，现在就是要适配cJSON这个库了

在thirdparty目录下新建目标三方库目录

然后在该目录下就是cJSON目录下新建一个HPKBUILD文件

6.3 编写HPKBUILD文件

HPKBUILD文件简单来说就是一个文件，运行之后他就会把我们的这个目标库进行编译，生成一些能在鸿蒙平台运行的文件，然后我们就是要编写这个HPKBUILD文件，下面我以cmake方式编译配置文件来写HPKBUILD文件,关于HPKBUILD这个文件的具体详情以及里面的函数的具体实现，可以去看徐老师的这篇文章鸿蒙PC三方库构建总指挥HPKBUILD（sha）库为例

HPKBUILD代码，位置是tpc_c_cplusplus/thirdparty/cJSON

pkgname=cJSON # 三方库名称（必填）
pkgver=v1.7.19  # 三方库版本（必填）
pkgrel=0
pkgdesc=""
url="https://github.com/DaveGamble/cJSON"   # 官方链接（可选）
archs=("armeabi-v7a" "arm64-v8a")   # CPU架构，默认即可
license=("MIT")
depends=()
makedepends=()
​
source="https://github.com/DaveGamble/$pkgname/archive/refs/tags/$pkgver.tar.gz"    # 库源码下载链接
​
autounpack=true # 是否自动下载压缩包，如若不写默认 true. (应对一些特殊情况，代码只能 git clone (项目中依赖 submoudle ))
downloadpackage=true # 是否自动解压，如若不写默认 true, 如果为 false 则需要用户在 prepare 函数中自行解压
buildtools="cmake" # 编译方法, 暂时支持cmake, configure, make等, 是什么就填写什么. 如若不写默认为cmake.
​
builddir=$pkgname-${pkgver:1} # 源码压缩包解压后目录名 编译目录名
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 -j4 -C $ARCH-build >> `pwd`/$ARCH-build/build.log 2>&1
    ret=$?
    cd $OLDPWD
    return $ret
}
​
package() {
    cd $builddir
    $MAKE VERBOSE=1 -C $ARCH-build install >> $buildlog 2>&1
    cd $OLDPWD
}
​
check() {
    echo "The test must be on an OpenHarmony device!"
}
​
# 清理环境
cleanbuild(){
    rm -rf ${PWD}/$builddir #${PWD}/$packagename
}
​

步骤 7：编译三方库

编写完HPKBUILD文件，配置完三方库的编译方式参数后，在tpc_c_cplusplus/lycium目录执行./build.sh pkgname，就会进行自动编译三方库，并打包安装到当前目录的usr/目录

在编译完成后就会在lycium/usr目录生成cJSON编译构建产物

至此，完成了从零到一的C/C++快速交叉编译构建工作。

---

相关资源

• C/C++三方库鸿蒙化适配一篇搞定从环境到交叉编译，祝你coding快乐_开源鸿蒙交叉编译工具链-CSDN博客

• 在 Windows 10 上安装和使用 WSL 2 安装 Ubuntu24详细指南_wsl2-CSDN博客

• 鸿蒙PC三方库构建总指挥HPKBUILD（sha）库为例

• 开源鸿蒙跨平台社区

• tpc_c_cplusplus:基于OpenHarmony的C/C++三方库适配项目 - AtomGit | GitCode

• OpenHarmony社区 - AtomGit | GitCode

---

总结

C库适配的核心就是"交叉编译"——使用交叉编译工具链，编译出能在鸿蒙设备上运行的库文件。

关键步骤：

1. 搭建Linux开发环境

2. 安装交叉编译工具链

3. 配置OpenHarmony SDK

4. 分析目标库依赖和构建系统

5. 编写交叉编译配置文件（CMakeLists.txt + toolchain.cmake）

6. 编译并验证产物

祝适配顺利！