鸿蒙PC平台三方库移植实战：以libogg库移植为例（附完整移植流程与工具链配置）

前言 鸿蒙PC生态的拓展与三方库移植意义

随着HarmonyOS正式进军PC领域，构建完善的软件生态成为关键。由于鸿蒙PC版的底层基于OpenHarmony与Linux内核的混合架构，现有Linux/Windows平台的开源库需要针对鸿蒙PC进行交叉编译与系统级适配。本文将以开源音频库libogg为例，详细介绍如何在鸿蒙PC平台上完成三方库的移植，并提供可复用的工程化方案。

---

一、移植工具链环境搭建

鸿蒙PC开发需使用专用的交叉编译工具链，关于环境的搭建，参见猫哥的上一篇博文：
《鸿蒙PC生态三方软件移植：开发环境搭建及三方库移植指南》

以下是核心环境配置步骤：

1. 配置SDK路径与基础工具链

虽然啊，官方提供的有示例的项目工程,build.sh构建脚本。但是呢，那个适合批量化。默认配置一次的构建了N多个写在dependcy.json文件中的库，不太方便调试。而我这个呢，适合单独对某个库进行方便的编译测试。

在于build.sh脚本同目录下创建 exports.sh 文件，先不使用build.sh构建脚本。

声明SDK路径与编译工具：

echo "hello exports"## 你的SDK路径，根据你实际的改下配置
SDK_PATH="/root/ohos-sdk/linux"echo "SDK_PATH:$SDK_PATH"export OHOS_SDK="$SDK_PATH"
export HNP_PERFIX=export COMPILER_TOOLCHAIN=${OHOS_SDK}/native/llvm/bin/BUILD_OS=$(uname)PYTHON=$(python --version)
echo "python  : $PYTHON"export CC=${COMPILER_TOOLCHAIN}clang             && echo "CC      : ${CC}"
export CXX=${COMPILER_TOOLCHAIN}clang++          && echo "CXX     : ${CXX}"
export HOSTCC=${CC}                              && echo "HOSTCC  : ${HOSTCC}"
export HOSTCXX=${CXX}                            && echo "HOSTCXX : ${HOSTCXX}"
export CPP="${CXX}  -E"                          && echo "CPP     : ${CPP}"
export AS=${COMPILER_TOOLCHAIN}llvm-as           && echo "AS      : ${AS}"
export LD=${COMPILER_TOOLCHAIN}ld.lld            && echo "LD      : ${LD}"
export STRIP=${COMPILER_TOOLCHAIN}llvm-strip     && echo "STRIP   : ${STRIP}"
export RANLIB=${COMPILER_TOOLCHAIN}llvm-ranlib   && echo "RANLIB  : ${RANLIB}"  
export OBJDUMP=${COMPILER_TOOLCHAIN}llvm-objdump && echo "OBJDUMP : ${OBJDUMP}"
export OBJCOPY=${COMPILER_TOOLCHAIN}llvm-objcopy && echo "OBJCOPY : ${OBJCOPY}"
export NM=${COMPILER_TOOLCHAIN}llvm-nm           && echo "NM      : ${NM}"
export AR=${COMPILER_TOOLCHAIN}llvm-ar           && echo "AR      : ${AR}"export SYSROOT=${OHOS_SDK}/native/sysroot
export PKG_CONFIG_SYSROOT_DIR=${SYSROOT}/usr/lib/aarch64-linux-ohos
export PKG_CONFIG_PATH=${PKG_CONFIG_SYSROOT_DIR}
export PKG_CONFIG_EXECUTABLE=${PKG_CONFIG_SYSROOT_DIR}export HNP_TOOL=${OHOS_SDK}/toolchains/hnpcli
export CMAKE=${OHOS_SDK}/native/build-tools/cmake/bin/cmake
export TOOLCHAIN_FILE=${OHOS_SDK}/native/build/cmake/ohos.toolchain.cmakeexport WORK_ROOT=${PWD}
export ARCHIVE_PATH=${WORK_ROOT}/output
export COMM_DEP_PATH=${WORK_ROOT}/deps_installexport HNP_PUBLIC_PATH=${HNP_PERFIX}/data/service/hnp/
export MAKE_QUITE_PARAM=" -s "
export CONFIGURE_QUITE_PARAM=" --quiet "export TARGET_PLATFORM=aarch64-linux-ohosexport CFLAGS="-fPIC -D__MUSL__=1 -D__OHOS__ -fstack-protector-strong --target=${TARGET_PLATFORM} -fuse-ld=${LD} --sysroot=${SYSROOT}"
export CXXFLAGS="${CFLAGS} "
export LD_LIBRARY_PATH=${SYSROOT}/usr/lib:${LD_LIBRARY_PATH}
export LDFLAGS="${LDFLAGS} -fuse-ld=${LD} --target=${TARGET_PLATFORM} --sysroot=${SYSROOT}"
export HOST_TYPE="--host=aarch64-linux --build=aarch64-linux"#export NCURSES_INSTALL_HNP_PATH="${HNP_PUBLIC_PATH}/ncurses.org/ncurses_v6.4"
mkdir -p ${HNP_PUBLIC_PATH}
mkdir -p ${ARCHIVE_PATH}mkdir -p code#export PKG_CONFIG_PATH="${CUSTOM_PREFIX}/lib/pkgconfig:$PKG_CONFIG_PATH"

通过执行 source exports.sh 激活环境。

source exports.sh

2. CMake工具链配置

鸿蒙SDK提供专用的ohos.toolchain.cmake文件，该配置也已经写到exports.sh中了。这里只是说明下，它用于指导CMake的交叉编译行为：

export TOOLCHAIN_FILE=${OHOS_SDK}/native/build/cmake/ohos.toolchain.cmake

---

二、libogg库移植实战

libogg 是Xiph.Org基金会维护的开源多媒体容器库，专门用于处理 Ogg比特流格式（一种自由、开放的多媒体容器格式）。Ogg格式广泛应用于音频（如Vorbis、Opus）、视频（Theora）等编码数据的封装，具有跨平台、低开销、流式传输友好的特点。作为Ogg生态的核心基础库，libogg提供了数据封装/解封装的核心能力，是众多开源音频项目（如VLC、FFmpeg）的底层依赖。

官方网站‌：访问 https://www.xiph.org/ogg/
libogg库下载地址：https://www.xiph.org/downloads/

gitcode上建了个仓：https://gitcode.com/qq8864/libogg

1. 源码准备与构建脚本

在libogg源码根目录创建 build_ohos.sh：

#!/bin/bash
# 编译安装libogg
${CMAKE} \-DCMAKE_TOOLCHAIN_FILE=${TOOLCHAIN_FILE} \-DCMAKE_BUILD_TYPE=Release \-DBUILD_SHARED_LIBS=ON \-DCMAKE_INSTALL_PREFIX=${LIBOGG_INSTALL_HNP_PATH} make VERBOSE=1 -j$(nproc) 
make install# 生成鸿蒙HNP软件包
cp hnp.json ${LIBOGG_INSTALL_HNP_PATH}/
pushd ${LIBOGG_INSTALL_HNP_PATH}/../${HNP_TOOL} pack -i ${LIBOGG_INSTALL_HNP_PATH} -o ${ARCHIVE_PATH}/tar -zvcf ${ARCHIVE_PATH}/ohos_libogg_1.3.6.tar.gz libogg_1.3.6/
popd

2. 关键编译参数解析

• -DCMAKE_TOOLCHAIN_FILE：指定鸿蒙交叉编译配置文件，自动处理ABI、sysroot路径。
• -DBUILD_SHARED_LIBS=ON：生成动态库（.so），适配鸿蒙动态链接机制。
• -DCMAKE_INSTALL_PREFIX：设置库的安装路径，需匹配鸿蒙的文件系统规范。

3. 鸿蒙HNP包封装

需现在libogg项目根目录下建个hnp.json元数据文件，用于对包就行描述。

hnp.json文件内容：

{"type":"hnp-config","name":"libogg","version":"1.3.6","install":{}
}

使用鸿蒙提供的hnpcli工具打包库文件：

# 示例：生成.hnp格式软件包
${HNP_TOOL} pack -i ${LIBOGG_INSTALL_HNP_PATH} -o ${ARCHIVE_PATH}/

生成的 .hnp 包可直接通过鸿蒙的软件管理工具安装。

开始执行编译

#前面，确保已执行过一次source exports.sh
#给脚本可执行权限
chmod +x build_ohos.sh
#在libogg项目根目录下执行脚本
./build_ohos.sh

---

编译成功截图：

编译注意事项

如果待移植的项目中支持cmake的话，建议最好直接用cmake。这样会简单太多。否则使用configure脚本配置参数的方式，去生成makefile再去编译的话，有时候不是那么顺利。比如libogg这个库，猫哥一开始用configure脚本生成makefile的形式。

编译报错：

有知道原因的小伙伴吗？

一开始的构建脚本build_ohos.sh是这样写的：

export LIBOGG_INSTALL_HNP_PATH=${HNP_PUBLIC_PATH}/libogg.org/libogg_1.3.6make clean./configure  --host=aarch64-linux-musl \--prefix=${LIBOGG_INSTALL_HNP_PATH} make VERBOSE=1 -j$(nproc)
make installcp hnp.json ${LIBOGG_INSTALL_HNP_PATH}/
pushd ${LIBOGG_INSTALL_HNP_PATH}/../${HNP_TOOL} pack -i ${LIBOGG_INSTALL_HNP_PATH} -o ${ARCHIVE_PATH}/tar -zvcf ${ARCHIVE_PATH}/ohos_libogg_1.3.6.tar.gz libogg_1.3.6/
popd

三、验证与调试

1. 库文件验证

检查输出是否包含鸿蒙平台的目标文件：

file ${LIBOGG_INSTALL_HNP_PATH}/lib/libogg.so
# 预期输出：ELF 64-bit LSB shared object, ARM aarch64, version 1 (SYSV), dynamically linked, ... 

2. 运行时依赖检查

通过 ldd 命令验证动态库依赖是否满足：

ldd ${LIBOGG_INSTALL_HNP_PATH}/lib/libogg.so
# 应显示鸿蒙系统库路径，例如：/system/lib/libc.so

---

四、工程化建议

1. 依赖管理

• 使用 dependency.json 文件声明库版本及依赖关系，例如：

{"name": "libogg","version": "1.3.6","dependencies": [],"platform": "aarch64-linux-ohos"
}

2. 自动化构建

集成CI/CD流程（如GitHub Actions），实现源码拉取、编译、测试、打包全流程自动化。

3. 提交至鸿蒙社区

将移植成果提交至 OpenHarmonyPCDeveloper社区，推动生态共建。

---

五、总结

通过本文方案，开发者可快速将Linux平台开源库（如libogg、libvorbis等）移植至鸿蒙PC平台。关键在于：

1. 正确配置交叉编译工具链，确保生成目标码兼容鸿蒙指令集与ABI。
2. 合理使用CMake参数，适配鸿蒙的系统特性（如musl libc）。
3. 遵循鸿蒙软件包规范，生成标准化交付件。

---

附录

• 鸿蒙PC开发工具链下载
• libogg官方源码仓库
• HNP打包工具文档