OpenHarmony 跨端框架与 C/C++ 库鸿蒙化适配实录

KMP 鸿蒙适配版

Kotlin Multiplatform 的鸿蒙版仓库：https://atomgit.com/OpenHarmony-kmp。它主打跨 Android/鸿蒙/桌面的原生 Kotlin 开发，无缝兼容 ArkTS，适合 Kotlin 技术栈的团队。

Capacitor 兼容说明

Ionic 团队的 Capacitor 没有出独立的鸿蒙版，但它本身支持 Web + 原生混合开发，在鸿蒙上可以直接跑。仓库：https://github.com/ionic-team/capacitor

桌面端补充：PC 生态适配

鸿蒙在桌面端的布局主要分两块：Electron 桌面应用适配和 PC 命令行工具移植。

Electron 鸿蒙桌面版

Electron 有专门的鸿蒙适配版，仓库有两个：

• https://atomgit.com/OpenHarmony-electron
• https://atomgit.com/openharmony-sig/electron

适配后 Electron 的 API 体系完全兼容，底层对接了鸿蒙桌面系统能力，应用迁移基本无感知。

PC 命令行工具

这个方向的核心就是工具化。所有 PC 端的命令行工具、终端工具，通过鸿蒙的交叉编译能力都能跑起来。它没有固定的适配模板，主要依赖下面要讲的通用 C/C++ 库编译方案来完成构建。

重头戏：通用 C/C++ 三方库的标准化鸿蒙化

鸿蒙底层能力和大部分三方库生态其实都靠 C/C++ 库在撑。官方对这一块的适配做了极致的标准化，所有库的适配流程、文件结构完全一样，只围绕固定的 6 个文件来搞，不用额外开发。

适配产出的 6 个文件

每个 C/C++ 库的鸿蒙化适配最终都会产出下面这 6 个文件：

├── HPKBUILD        # 编译构建脚本（核心，configure/cmake/make 逻辑全在这里）
├── HPKCHECK        # 设备端测试脚本
├── README.OpenSource # 开源声明，填写协议、版权、源码来源
├── README_zh.md    # 中文说明，写编译步骤和注意事项
├── SHA512SUM       # 可选，源码包哈希校验
└── xxx_oh_pkg.patch # 按需创建，解决编译兼容性问题的补丁

这些文件都有官方标准模板，地址：https://gitcode.com/openharmony-sig/tpc_c_cplusplus/tree/master/lycium/template

HPKBUILD：编译核心

HPKBUILD 是一个 Shell 脚本，定义了库的元信息、源码下载地址、交叉编译环境配置、构建逻辑、打包安装，以及测试前的准备和环境清理。官方模板已经很完善，实战时只要照着改就行。

下面是官方标准模板，去掉了一些注释：

pkgname=NAME
pkgver=VERSION
pkgrel=0
pkgdesc=""
url=""
archs=("armeabi-v7a" "arm64-v8a")
license=()
depends=()
makedepends=()
source="https://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz"
downloadpackage=true
autounpack=true
buildtools=
builddir=
packagename=$builddir.tar.gz

prepare(){
  cd $builddir
  cd ${OLDPWD}
}

build(){
  cd $builddir
  ${OHOS_SDK}/native/build-tools/cmake/bin/cmake "$@" -DOHOS_ARCH=$ARCH -B$ARCH-build -S./ -L
  make -j4 -C $ARCH-build
  ret=$?
  cd $OLDPWD
  return $ret
}

package(){
  cd $builddir
  make -C $ARCH-build install
  cd $OLDPWD
}

check(){
  echo "The test must be on an OpenHarmony device!"
}

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

实战案例 1：fftw3（纯算法库，configure 编译）

这是一个没有外部依赖的库，用 configure 方式编译：

pkgname=fftw3
pkgver=3.3.10
pkgrel=0
pkgdesc="FFTW is a C subroutine library for computing the discrete Fourier transform..."
url="http://fftw.org/"
archs=("armeabi-v7a" "arm64-v8a")
license=("GPL-2.0-or-later")
depends=()
makedepends=()
source="http://fftw.org/fftw-${pkgver}.tar.gz"
autounpack=true
downloadpackage=true
buildtools="configure"
builddir=fftw-$pkgver
packagename=$builddir.tar.gz
source envset.sh
host=
optargs=

prepare(){
  mkdir -p $builddir/$ARCH-build
  if [ $ARCH == "armeabi-v7a" ]; then setarm32ENV; host=arm-linux; fi
  if [ $ARCH == "arm64-v8a" ]; then setarm64ENV; host=aarch64-linux; fi
  optargs="--enable-single --with-slow-timer"
}

build(){
  cd $builddir/$ARCH-build
  PKG_CONFIG_LIBDIR="${pkgconfigpath}" ../configure "$@" $optargs --enable-threads --enable-shared --host=$host >$buildlog 2>&1
  $MAKE VERBOSE=1 >>$buildlog 2>&1
  ret=$?
  cd $OLDPWD
  return $ret
}

package(){
  cd $builddir/$ARCH-build
  $MAKE VERBOSE=1 install >>$buildlog 2>&1
  cd $OLDPWD
  if [ $ARCH == "armeabi-v7a" ]; then unsetarm32ENV; fi
  if [ $ARCH == "arm64-v8a" ]; then unsetarm64ENV; fi
  unset host optargs
}

check(){
  cd $builddir/$ARCH-build
  sed -i '/.*check-local: bench$(EXEEXT)/c\check-local: #bench$(EXEEXT)' tests/Makefile
  sed -i "s#/usr/bin/sed#sed#g" tests/bench
  sed -i "s#/bin/bash#/data/CIusr/bin/bash#g" tests/Makefile tests/bench
  cd $OLDPWD
  echo "The test must be on an OpenHarmony device!"
}

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

实战案例 2：tassl（带依赖 + 补丁，configure 编译）

tassl 依赖 openssl 和 zlib，并且需要打补丁：

pkgname=tassl
pkgver=1.1.1
pkgrel=0
pkgdesc="TASSL is an SSL/TLS protocol implementation that supports national secret algorithms"
url="https://github.com/jntass/TASSL-1.1.1"
archs=("armeabi-v7a" "arm64-v8a")
license=("OpenSSL")
depends=(openssl_1_1_1w zlib_1_3_1)
makedepends=()
commitId="a30d107669fdf7d6909b10f1e179de4aaff38ff5"
source="https://github.com/jntass/$pkgname-$pkgver/archive/$commitId.zip"
autounpack=true
downloadpackage=true
buildtools="configure"
builddir=TASSL-${pkgver}-$commitId
packagename=$builddir.zip
source envset.sh
patchflag=true

prepare(){
  if $patchflag; then
    cd $builddir
    patch -p1 < `pwd`/../tassl_oh_pkg.patch >>$publicbuildlog 2>&1
    patchflag=false
    cd $OLDPWD
  fi
  cp -rf $builddir ${builddir}-${ARCH}-build
  if [ $ARCH == "armeabi-v7a" ]; then setarm32ENV
  elif [ $ARCH == "arm64-v8a" ]; then setarm64ENV
  else echo "${ARCH} not support"; return -1; fi
}

build(){
  cd $builddir-$ARCH-build
  ./config "$@" no-asm >$buildlog 2>&1
  $MAKE >>$buildlog 2>&1
  ret=$?
  cd $OLDPWD
  return $ret
}

package(){
  cd $builddir-$ARCH-build
  mkdir -p ${LYCIUM_ROOT}/usr/${pkgname}/${ARCH}/
  $MAKE install >>$buildlog 2>&1
  cd $OLDPWD
}

check(){
  if [ $ARCH == "armeabi-v7a" ]; then unsetarm32ENV
  elif [ $ARCH == "arm64-v8a" ]; then
    cd $builddir-$ARCH-build
    sed -i.bak "s|PERL=/usr/bin/perl|PERL=/data/CIusr/bin/perl|g" ./Makefile
    make test >>$buildlog 2>&1
    cd $OLDPWD
    unsetarm64ENV
  else echo "${ARCH} not support"; return -1; fi
  echo "The test must be on an OpenHarmony device!"
}

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

HPKCHECK：测试脚本

测试脚本也高度模板化，所有库的结构都一样，只需要把执行测试的那一行命令改成对应的 ctest 或 make test 就行。注意测试必须在鸿蒙真机上跑，模拟器不支持。

source HPKBUILD > /dev/null 2>&1
logfile=${LYCIUM_THIRDPARTY_ROOT}/${pkgname}/${pkgname}_${ARCH}_${OHOS_SDK_VER}_test.log

checkprepare(){
  return 0
}

openharmonycheck(){
  res=0
  cd ${builddir}/${ARCH}-build
  ctest >${logfile} 2>&1
  res=$?
  cd $OLDPWD
  return $res
}

其他四个文件

• README.OpenSource：固定格式，填协议、版权、源码地址。
• README_zh.md：写编译步骤和说明，格式不限。
• SHA512SUM：不校验的话可以不要；需要就生成源码包的哈希值。
• xxx_oh_pkg.patch：按需创建，通常是一些路径、接口兼容性修复，在 prepare 阶段用 patch -p1 打上去。

C/C++ 库编译的核心要点

所有编译都基于鸿蒙的交叉编译环境，HPKBUILD 里最核心的逻辑其实就几条：

• 只适配两个架构：armeabi-v7a 和 arm64-v8a。
• 通过 source envset.sh 导入环境，然后用 setarm32ENV/setarm64ENV 切换。
• 编译方式支持 configure、make、cmake，三种都兼容。
• 编译产物最终安装到 ${LYCIUM_ROOT}/usr/${pkgname}/${ARCH}/，鸿蒙系统直接能调用。

仓颉语言的三方库生态

仓颉（CangJie）是 OpenHarmony 官方原生语言，为鸿蒙开发设计，语法简洁，性能不错，未来会是鸿蒙原生应用的首选。它的库天生不需要鸿蒙化适配，直接就能跑在设备上。

核心资源：

• 官方库合集：https://gitcode.com/cj-awesome
• 库标准化模板：https://gitcode.com/cj-awesome/template
• 语言文档：https://cangjie-lang.cn/playground
• 鸿蒙生态文档：https://atomgit.com/openharmony-sig/docs_cangjie

仓颉可以无缝调用鸿蒙的 C/C++ 库，和上面那套通用 C/C++ 库生态正好互补。

适配优先级与原则

实际项目中，适配成本从低到高大概是这样：

1. 纯 Dart 的 Flutter 库：零成本，直接复用。
2. 仓颉语言三方库：零成本，原生支持。
3. 没有 android/ios 目录的跨端库：零成本，开箱即用。
4. 通用 C/C++ 三方库：低成本，按模板改 6 个文件就行。
5. 带原生桥接层的跨端库（Flutter/RN/Cordova 等）：中等成本，在官方适配版桥接层上改，不用重构。
6. PC 命令行工具或桌面工具：成本稍高，要在 C/C++ 交叉编译方案上移植，没有固定模板。

几点原则：

• 所有适配都尽量用官方标准化方案，不要自己另搞一套。
• 跨端框架优先选官方的 XX-OH 适配版，别自己从头适配。
• C/C++ 库严格按 6 个文件那套标准来，这是硬性规范。
• 新项目里可以优先考虑用仓颉开发原生能力。

核心资源汇总

• Flutter-OH：https://atomgit.com/OpenHarmony-Flutter
• RN-OH：https://atomgit.com/openharmony-rn
• Cordova-OH：https://atomgit.com/OpenHarmony-Cordova
• Electron-OH：https://atomgit.com/OpenHarmony-electron
• C/C++ 库适配模板：https://gitcode.com/openharmony-sig/tpc_c_cplusplus
• 仓颉库合集：https://gitcode.com/cj-awesome