HarmonyOS Next构建工具 lycium 原理介绍

在这里插入图片描述

背景介绍

HarmonyOS Next中很多系统API是以C++接口提供，如果要使用C++接口，必须要使用NAPI在ArkTS与C++间交互，这种场景在使用DevEco-Studio中集成的交叉编译工具，以及cmake构建工具就完全够用了。但是针对一些三方库迁移的场景，比如ffmpeg、openssl等，如果自己配置编译环境和脚本比较麻烦，进行交叉编译的过程中较关注的问题是：不同编译构建方式如何进行交叉编译、不同的编译构建平台如何配置交叉编译的环境、不同的交叉编译架构如何配置以及交叉编译后的产物如何进行测试验证。当前开源的C/C++三方库编译方式多样化，以下为主流的几种交叉编译方式：

cmake 编译构建。
configure 编译构建方式。
make 编译构建。
官方提供了交叉编译构建工具lycium，帮助我们快速构建三方库。

lycium工具介绍

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

lycium的构建原则是移植过程，不可以改源码（即不patchc/cpp文件，不patch构建脚本）。如移植必须patch，patch必须评审，给出充分理由。（不接受业务patch）

lycium构建工具地址：https://gitee.com/openharmony-sig/tpc_c_cplusplus

使用示例

编译环境准备：lycium框架支持多种构建方式的三方库，为了保障三方库能正常编译，我们需要保证编译环境中包含以下几个基本编译命令： gcc, cmake, make, pkg-config, autoconf, autoreconf, automake, 如若缺少相关命令，可通过官网下载对应版本的工具包，也可以在编译机上通过命令安装，如若Ubuntu系统上缺少cmake可以通过以下命令安装：sudo apt install cmake
修改三方库的编译方式以及编译参数，lycium框架提供了HPKBUILD文件供开发者对相应的C/C++三方库的编译配置。具体方法：
- 在thirdparty目录下新建需要共建的三方库名字pkgname。
- 将HPKBUILD模板文件拷贝到新建三方库目录下。
- 根据三方库实际情况修改HPKBUILD模板，文件修改可参考minizip共建。
快速编译三方库：配置完三方库的编译方式参数后，在lycium目录执行./build.sh pkgname，进行自动编译三方库，并打包安装到当前目录的 usr/pkgname/
ARCH 目录./build.sh # 默认编译 thirdparty 目录下的多有库，也可以：./build.sh aaa bbb ccc ... # 编译 thirdparty 目录下指定的 aaa bbb ccc ...库当 aaa 库存在依赖时，必须保证入参中包含依赖，否则 aaa 库不会编译

lycium框架是通过linux shell脚本语言编写的，接下来我们分析构建工具的shell代码，理解构建流程，有助于帮助我们定位编译时遇到的失败问题。

构建脚本原理介绍

lycium框架主要由以下几个部分组成:

HPKBUILD 构建配置
顶层构建脚本 build.sh
交叉编译工具链
测试验证环境

构建流程

1. 构建配置准备

开发者需要在 thirdparty 目录下为待编译的三方库创建目录,并编写 HPKBUILD 构建配置文件。HPKBUILD 文件定义了:

源码获取方式
编译参数配置
依赖关系声明
安装规则

HPKBUILD构建配置文件示例：

# Contributor: Jeff Han <hanjinfei@foxmail.com>
# Maintainer: Jeff Han <hanjinfei@foxmail.com>
pkgname=FFmpeg
pkgver=n6.0
pkgrel=0
pkgdesc="FFmpeg is a collection of libraries and tools to process multimedia content such as audio, video, subtitles and related metadata."
url="https://github.com/FFmpeg/FFmpeg/"
archs=("armeabi-v7a" "arm64-v8a")
license=("GPL2" "GPL3" "LGPL3" "MIT" "X11" "BSD-styl")
depends=("rtmpdump" "openssl_1_0_2u")
makedepends=()
source="https://github.com/FFmpeg/$pkgname/archive/refs/tags/$pkgver.tar.gz"autounpack=false
downloadpackage=true
buildtools="configure"builddir=$pkgname-${pkgver}
packagename=$builddir.tar.gz
source envset.sh
buildhost=true
arch=
ldflags=prepare() {if [ "$LYCIUM_BUILD_OS" == "Linux" ]thenhostosname=linuxelif [ "$LYCIUM_BUILD_OS" == "Darwi" ]thenhostosname=darwinelseecho "System cannot recognize, exiting"return -1fiif [ $buildhost == true ]thentar -zxf $packagenamecd $builddir./configure --enable-static --enable-shared --disable-doc --disable-htmlpages \--target-os=$hostosname --disable-optimizations --prefix=`pwd`/hostbuild > $publicbuildlog 2>&1$MAKE >> $publicbuildlog 2>&1$MAKE install >> $publicbuildlog 2>&1export LD_LIBRARY_PATH=`pwd`/hostbuild/lib:$LD_LIBRARY_PATHsed -i.bak 's/include $(SRC_PATH)\/tests\/fate\/source.mak/#include $(SRC_PATH)\/tests\/fate\/source.mak/g' tests/Makefile$MAKE check >> $publicbuildlog 2>&1ret=$?buildhost=falsecd $OLDPWDfimkdir $pkgname-$ARCH-buildtar -zxf $packagename -C $pkgname-$ARCH-buildcd  $pkgname-$ARCH-build/$builddirpatch -p1 < ../../FFmpeg_oh_test.patchcd $OLDPWDif [ $ARCH == "armeabi-v7a" ]thensetarm32ENVarch=armldflags="-L${OHOS_SDK}/native/sysroot/usr/lib/arm-linux-ohos"elif [ $ARCH == "arm64-v8a" ]thensetarm64ENVarch=aarch64ldflags="-L${OHOS_SDK}/native/sysroot/usr/lib/aarch64-linux-ohos"elseecho "${ARCH} not support"return -1fireturn $ret
}build() {cd $pkgname-$ARCH-build/$builddirPKG_CONFIG_LIBDIR="${pkgconfigpath}" ./configure "$@" --enable-neon --enable-asm --enable-network \--disable-vulkan --enable-cross-compile --enable-librtmp --disable-x86asm --enable-openssl --enable-protocols \--enable-static --enable-shared --disable-doc --disable-htmlpages --target-os=linux --arch=$arch \--cc=${CC} --ld=${CC} --strip=${STRIP} --host-cc="${CC}" --host-ld="${CC}" --host-os=linux \--host-ldflags=${ldflags} --sysroot=${OHOS_SDK}/native/sysroot > $buildlog 2>&1$MAKE >> $buildlog 2>&1ret=$?cd $OLDPWDreturn $ret
}package() {cd $pkgname-$ARCH-build/$builddir$MAKE install >> $buildlog 2>&1cd $OLDPWD
}checktestfiles() {cd $pkgname-$ARCH-build/$builddir/tests/reftmpdir=("fate" "acodec" "lavf" "lavf-fate" "pixfmt" "seek" "vsynth")for dir in ${tmpdir[*]}dofor file in `ls $dir`doif [ ! -f $dir/$file ]; thencontinuefistr=`cat $dir/$file | grep "\*tests"`if [ ! -z "$str" ]thensed -i.bak 's/\*tests/tests/g' $dir/$filefidonedonecd $OLDPWD
}copyhostbin() {file=$1if [[ -f tests/$file ]] && [[ ! -f tests/$file.${ARCH} ]]thenmv tests/$file tests/$file.${ARCH}cp ../../$builddir/tests/$file tests/$filefi
}check() {cd $pkgname-$ARCH-build/$builddir# disable running cmdsed -i.bak 's/	$(Q)$(SRC_PATH)\/tests\/fate-run.sh/#	$(Q)$(SRC_PATH)\/tests\/fate-run.sh/g' tests/Makefile# disable check git sourcessed -i.bak 's/include $(SRC_PATH)\/tests\/fate\/source.mak/#include $(SRC_PATH)\/tests\/fate\/source.mak/g' tests/Makefile# disable check ffprobe,this use xmllint command, which ohos is not supportsed -i.bak 's/include $(SRC_PATH)\/tests\/fate\/ffprobe.mak/#include $(SRC_PATH)\/tests\/fate\/ffprobe.mak/g' tests/Makefile# change x86 cmd for generate test targetmv ffmpeg ffmpeg.${ARCH}cp ../../$builddir/ffmpeg ./retrytimes=0ret=0while truedo$MAKE check >> $buildlog 2>&1if [ $? -eq 0 ]thenbreak;ficopyhostbin base64copyhostbin audiomatchcopyhostbin audiogencopyhostbin videogencopyhostbin tiny_psnrcopyhostbin tiny_ssimcopyhostbin rotozoomlet retrytimes=$retrytimes+1if [ $retrytimes -gt 4 ]thenret=1breakfidonemv ffmpeg.${ARCH} ffmpegfor file in `ls tests/*.${ARCH}`dotmpfile=${file%.*}mv $file $tmpfiledone# reduction running cmd for real testsed -i.bak 's/#	$(Q)$(SRC_PATH)\/tests\/fate-run.sh/	$(Q)$(SRC_PATH)\/tests\/fate-run.sh/g' tests/Makefilecd $OLDPWDchecktestfilesecho "The test must be on an OpenHarmony device!"# skip running test on host# real test CMD# make checkreturn $ret
}recoverpkgbuildenv() {unset archunset ldflagsif [ $ARCH == "armeabi-v7a" ]thenunsetarm32ENVelif [ $ARCH == "arm64-v8a" ]thenunsetarm64ENVelseecho "${ARCH} not support"return -1fi
}# 清理环境
cleanbuild() {rm -rf ${PWD}/${builddir} ${PWD}/$pkgname-arm64-v8a-build ${PWD}/$pkgname-armeabi-v7a-build #${PWD}/$packagename
}

2. 构建过程

主入口 build.sh 脚本执行以下步骤:

解析命令行参数,确定要编译的目标库
检查编译环境(编译工具链等)
读取目标库的 HPKBUILD 配置
按照依赖关系顺序编译各个库
对每个库执行:
- 获取源码
- 配置编译参数
- 执行编译
- 安装到指定目录

检查编译环境代码：

# 检测操作系统类型
unames=`uname -s`
osname=${unames:0:5}# 设置根目录
LYCIUM_ROOT=$(cd $(dirname ${BASH_SOURCE[0]}); pwd)# 检查 OHOS_SDK 环境
if [ -z ${OHOS_SDK} ]
thenecho "OHOS_SDK 未设置..."exit 1
fi

依赖管理检测：

# 依赖库暂存文件
depend_tmp_file="/tmp/$USER-lycium_deps-$build_time"
export LYCIUM_DEPEND_PKGNAMES=$depend_tmp_file# 已完成库列表
donelist=()
donelibs=()

核心函数 buildhpk() 实现了构建流程控制：

任务分轮次执行
处理依赖关系
错误处理机制
主要变量：

nextroundlist: 下一轮待构建项目
notdonelist: 未完成项目列表
buildfalselist: 构建失败项目列表

关键函数说明如下：
checkbuildenv()
检查必要的构建工具是否安装：

gcc, cmake, make 等基础工具
autoconf, automake 等自动化工具
git, curl 等辅助工具 prepareshell()
为每个构建目录准备必要的脚本：
build_hpk.sh: 项目构建脚本
envset.sh: 环境设置脚本 makelibsdir()
管理构建目录：
检查目录有效性
过滤已构建项目
添加到构建队列

3. 交叉编译支持

框架通过以下方式实现交叉编译:

使用 OpenHarmony NDK 提供的交叉编译工具链
在 HPKBUILD 中配置交叉编译相关参数
支持 arm32/arm64/x86 等多架构编译

4. 产物输出

编译产物按照如下结构组织:

usr/└── ${pkgname}/└── ${ARCH}/├── lib/      # 库文件├── include/  # 头文件└── bin/      # 可执行文件

build_hpk.sh构建脚本说明

核心构建函数说明：

1. prepare()

准备构建环境:

宿主机构建(buildhost=true时)
解压源码包
应用补丁
设置交叉编译环境

2. build()

执行构建过程:

配置构建参数
执行configure配置
执行make编译
返回构建结果

3. package()

安装打包:

执行make install
生成最终安装包

4. check()

测试验证:

修改测试配置
准备测试环境
执行测试用例
处理测试结果

5. 环境管理函数

recoverpkgbuildenv()
- 清理编译环境变量
- 恢复原始环境
cleanbuild()
- 清理构建目录
- 删除临时文件

总结

本文介绍了HarmonyOS Next跨平台构建脚本功能、使用、以及原理，介绍了构建脚本相关的shell代码等。