基于 OpenHarmony 的 libzip 适配与交叉编译实践：构建系统、依赖管理与 HNP 打包全解析

基于 OpenHarmony 的 libzip 适配与交叉编译实践构建系统、依赖管理与 HNP 打包全解析前言推动 PC 端 OpenHarmony 生态快速完善的过程中大量三方开源库需要完成适配、编译链路打通与 HNP 组件化发布而 libzip 则是文件压缩类库中最基础、使用最广的工具之一。无论是文件管理工具、更新包解析、应用安装器还是后台资源解压几乎都会依赖 ZIP 能力。因此将 libzip 成功迁移到 OpenHarmony 不仅是单一库的适配更是构建完整开发环境的重要一环。本文基于实际的 PC 端鸿蒙开发环境完整演示 libzip 的 交叉编译流程、CMake 构建配置、依赖声明、HNP 元数据定义、产物安装目录处理 以及最终的 HNP 打包产出流程。同时也补充了 GitCode 托管与适配仓库维护方法帮助开发者从零到一完成一个第三方库在鸿蒙上的全流程适配。希望本文能作为你后续适配更多三方开源库的标准模版参考。项目信息项目名称libzipZIP 文件处理类库开源协议BSD-3-Clause源码版本1.11.4基于 1.11.4_ohos 分支适配目标平台OpenHarmony PCaarch64-linux-ohos依赖项OpenHarmony SDK、CMake、hnpcli 工具操作系统平台开发WSL Ubuntu 22.04/24.04运行OpenHarmony PC核心适配目标完成 libzip 1.11.4 向 OpenHarmony PCaarch64 架构的交叉编译与 HNP 打包解决 CMake 版本兼容问题输出可直接集成的 ZIP 处理类库关键技术栈基于 OpenHarmony SDK 配置 CMake 交叉编译参数适配鸿蒙构建规范修复安装阶段的 CMake 命令参数错误核心价值为鸿蒙 PC 生态提供基础 ZIP 解析压缩能力同时沉淀了 C/C 类开源库适配鸿蒙的通用流程与版本兼容问题解决方案环境准备适配前必须完成的工具链与 SDK 配置Linux 进行鸿蒙 OpenHarmony适配的核心前提准备包括配置 Linux 环境如 Ubuntu 22.04并更换国内镜像源安装 Python3 及依赖工具下载并解压 OpenHarmony SDK 含 native、toolchains 组件准备构建脚手架及目标部件的源码完成鸿蒙化适配如添加构建脚本、配置文件修改源码兼容性下方汇总展示了多位老师在鸿蒙 OpenHarmony 适配方面的高质量教程如果在前提准备部分还有不清楚的地方可参考这些文章进行进一步学习以下资源不分先后顺序均具有参考价值资源类型描述链接基础环境搭建Windows 10 上安装和使用 WSL 2 安装 Ubuntu24详细指南点击查看Mac移植指南鸿蒙PC命令行适配指南Mac 版点击查看Win移植指南鸿蒙PC生态三方软件移植开发环境搭建及三方库移植指南点击查看全流程适配指南OpenHarmony Linux 命令行工具适配实战基于 Cursor × WSL 的 tree 2.2.1 交叉编译与 HNP 打包全流程指南点击查看官方构建文档社区维护的鸿蒙 PC 生态命令行工具构建脚手架点击查看libzip 鸿蒙适配与构建全流程指南切换到build/code目录通过 Git 从指定 GitCode 仓库地址克隆 libzip 工具的源码在当前目录生成libzip文件夹存放源码为后续开源鸿蒙适配准备基础源码# 进入build目录下的code子目录cdcode# 从GitCode仓库克隆libzip工具的源码到当前目录创建名为libzip的文件夹gitclone https://gitcode.com/gh_mirrors/li/libzip.gitdependency.json 配置声明 libzip 的鸿蒙依赖信息在 dependency.json 配置文件中定义 libzip 的依赖信息指定其名称、适配鸿蒙的 1.11.4_ohos 分支以及对应的 GitCode 仓库地址供构建流程拉取指定版本的 libzip 源码{dependency:[{name:libzip,branch:1.11.4_ohos,url:https://gitcode.com/weixin_62765017/libzip.git}]}build.sh 主构建脚本环境初始化与鸿蒙交叉编译配置这是 libzip 鸿蒙适配的主构建脚本先校验并传入鸿蒙 SDK 路径根据构建系统配置编译工具链检查 Python 依赖并给出系统适配的安装指引配置编译相关环境变量及鸿蒙编译参数默认进入 libzip 目录执行专属构建脚本也可通过参数按 dependency.json 拉取依赖构建#!/bin/bashSDK_PATHwhile[[$#-gt0]];docase$1in--sdk)SDK_PATH$2shift2;;*)echoError: unknow param$1echoUsage:$0--sdk SDK pathexit1;;esacdoneif[-z$SDK_PATH];thenechoError: SDK path must be specified with the\--sdk\optionechoUsage:$0--sdk SDK pathexit1fiif[!-d$SDK_PATH];thenechoError: SDK path is not exist or no permossion: [$SDK_PATH]exit2fiexportOHOS_SDK$SDK_PATHexportHNP_PERFIXBUILD_OS$(uname)case$BUILD_OSinOpenHarmony)echoBuild in: $(uname-a) by local tool chains.exportCOMPILER_TOOLCHAIN${OHOS_TOOL_CHAIN_PATH};;HarmonyOS)echoBuild in: $(uname-a) by local tool chains.exportCOMPILER_TOOLCHAIN${HMOS_TOOL_CHAIN_PATH}exportHNP_PERFIX${PWD}/hnp;;*)echoBuild in: $(uname-a) by cross tool chains.exportCOMPILER_TOOLCHAIN${OHOS_SDK}/native/llvm/bin/;;esacif[-z${HNP_PERFIX}];thenexportHNP_PERFIX${PWD}/hnpfiif[-n${HNP_PERFIX}];thenmkdir-p${HNP_PERFIX}fiPYTHON$(python--version)echopython :$PYTHONif[-z$PYTHON];thenechoYou need install python in your systemcase$BUILD_OSinOpenHarmony|HarmonyOS)echo${BUILD_OS}install by url://www.xxx.xxx.com;;Linux*)ifcommand-vapt-get/dev/null;thenecho1. sudo apt updateecho2. sudo apt install python3 python3-pipelifcommand-vyum/dev/null;thenecho1. sudo yum install python3 python3-pipelseechoPlease install python3 and pip using your systems package manager.fi;;Darwin*)echo1. Use Homebrew: brew install pythonechoorecho2. Download by python org: https://www.python.org/downloads/macos/;;CYGWIN*|MINGW32*|MSYS*|MINGW*)echo1. Download by python org: https://www.python.org/downloads/windows/echo2. Check the\Add Python to PATH\option during installation.;;*)echoUnable to determine the appropriate Python installation method for your system.;;esacexit1fiexportCC${COMPILER_TOOLCHAIN}clangechoCC :${CC}exportCXX${COMPILER_TOOLCHAIN}clangechoCXX :${CXX}exportHOSTCC${CC}echoHOSTCC :${HOSTCC}exportHOSTCXX${CXX}echoHOSTCXX :${HOSTCXX}exportCPP${CXX}echoCPP :${CPP}exportAS${COMPILER_TOOLCHAIN}llvm-asechoAS :${AS}exportLD${COMPILER_TOOLCHAIN}ld.lldechoLD :${LD}exportSTRIP${COMPILER_TOOLCHAIN}llvm-stripechoSTRIP :${STRIP}exportRANLIB${COMPILER_TOOLCHAIN}llvm-ranlibechoRANLIB :${RANLIB}exportOBJDUMP${COMPILER_TOOLCHAIN}llvm-objdumpechoOBJDUMP :${OBJDUMP}exportOBJCOPY${COMPILER_TOOLCHAIN}llvm-objcopyechoOBJCOPY :${OBJCOPY}exportNM${COMPILER_TOOLCHAIN}llvm-nmechoNM :${NM}exportAR${COMPILER_TOOLCHAIN}llvm-arechoAR :${AR}exportSYSROOT${OHOS_SDK}/native/sysrootexportPKG_CONFIG_SYSROOT_DIR${SYSROOT}/usr/lib/aarch64-linux-ohosexportPKG_CONFIG_PATH${PKG_CONFIG_SYSROOT_DIR}exportPKG_CONFIG_EXECUTABLE${PKG_CONFIG_SYSROOT_DIR}exportHNP_TOOL${OHOS_SDK}/toolchains/hnpcliexportCMAKE${OHOS_SDK}/native/build-tools/cmake/bin/cmakeexportTOOLCHAIN_FILE${OHOS_SDK}/native/build/cmake/ohos.toolchain.cmakeexportWORK_ROOT${PWD}exportARCHIVE_PATH${WORK_ROOT}/outputexportCOMM_DEP_PATH${WORK_ROOT}/deps_installexportHNP_PUBLIC_PATH${HNP_PERFIX}/data/service/hnp/exportMAKE_QUITE_PARAM -s exportCONFIGURE_QUITE_PARAM --quiet exportTARGET_PLATFORMaarch64-linux-ohosexportCFLAGS-fPIC -D__MUSL__1 -D__OHOS__ -fstack-protector-strong --target${TARGET_PLATFORM}-fuse-ld${LD}--sysroot${SYSROOT}exportCXXFLAGS${CFLAGS}exportLD_LIBRARY_PATH${SYSROOT}/usr/lib:${LD_LIBRARY_PATH}exportLDFLAGS${LDFLAGS}-fuse-ld${LD}--target${TARGET_PLATFORM}--sysroot${SYSROOT}exportHOST_TYPE--hostaarch64-linux --buildaarch64-linuxmkdir-p${HNP_PUBLIC_PATH}mkdir-p${ARCHIVE_PATH}mkdir-pcode# 默认直接构建指定目录除非显式要求按 dependency.json 走BUILD_BY_DEPENDENCY${BUILD_BY_DEPENDENCY:-false}# 需要构建的组件名称默认构建 libzipSPECIFIC_DIR${SPECIFIC_DIR:-libzip}if[[${BUILD_BY_DEPENDENCY}true]];thenpython build_dependency.pyelsepushdcode/${SPECIFIC_DIR}chmodx build_ohos.sh ./build_ohos.shpopdfihnp.json 配置HNP 组件元信息定义在 hnp.json 配置文件中定义 libzip 的 HNP 配置信息指定配置类型为 hnp-config、组件名称和版本号为空的 install 字段预留安装相关配置空间用于鸿蒙 HNP 打包时识别组件基础信息{type:hnp-config,name:libzip,version:1.11.4,install:{}}build_ohos.shlibzip 的鸿蒙平台专属构建脚本libzip 针对鸿蒙的专属构建脚本定义组件名称版本及安装路径清理并创建构建目录通过 CMake 配置鸿蒙编译参数指定工具链、关闭非必要功能、配置编译器 / 链接器参数编译并安装 libzip 到指定路径接着拷贝文档和 hnp.json 配置文件最后用 HNP 工具打包组件并生成压缩包完成鸿蒙适配的构建产物输出#!/bin/bashset-euopipefailcomponent_namelibzipcomponent_version1.11.4install_prefix/usrexportLIBZIP_INSTALL_HNP_PATH${HNP_PUBLIC_PATH}/${component_name}.org/${component_name}_${component_version}echoInstall root:${LIBZIP_INSTALL_HNP_PATH}mkdir-p${LIBZIP_INSTALL_HNP_PATH}# 清理之前的构建if[-dbuild];thenrm-rfbuildfimkdir-pbuild# 使用 CMake 配置和构建pushdbuild${CMAKE}..\-DCMAKE_TOOLCHAIN_FILE${TOOLCHAIN_FILE}\-DCMAKE_SYSROOT${SYSROOT}\-DCMAKE_INSTALL_PREFIX${install_prefix}\-DCMAKE_BUILD_TYPERelease\-DBUILD_SHARED_LIBSON\-DBUILD_TOOLSON\-DENABLE_OPENSSLOFF\-DENABLE_GNUTLSOFF\-DENABLE_MBEDTLSOFF\-DENABLE_COMMONCRYPTOOFF\-DENABLE_WINDOWS_CRYPTOOFF\-DENABLE_BZIP2OFF\-DENABLE_LZMAOFF\-DENABLE_ZSTDOFF\-DBUILD_REGRESSOFF\-DBUILD_EXAMPLESOFF\-DBUILD_DOCOFF\-DCMAKE_C_COMPILER${CC}\-DCMAKE_CXX_COMPILER${CXX}\-DCMAKE_C_FLAGS${CFLAGS}\-DCMAKE_CXX_FLAGS${CXXFLAGS}\-DCMAKE_EXE_LINKER_FLAGS${LDFLAGS}\-DCMAKE_SHARED_LINKER_FLAGS${LDFLAGS}\-DCMAKE_STATIC_LINKER_FLAGS${LDFLAGS}${CMAKE}--build.--configRelease--parallel$(nproc)DESTDIR${LIBZIP_INSTALL_HNP_PATH}${CMAKE}--install.--prefix${install_prefix}popd# 安装文档doc_dir${LIBZIP_INSTALL_HNP_PATH}/usr/share/doc/${component_name}mkdir-p${doc_dir}if[-fREADME.md];theninstall-m644README.md${doc_dir}/fiif[-fLICENSE];theninstall-m644LICENSE${doc_dir}/fiif[-fNEWS.md];theninstall-m644NEWS.md${doc_dir}/fi# 安装 hnp.jsoninstall-m644hnp.json${LIBZIP_INSTALL_HNP_PATH}/pushd${LIBZIP_INSTALL_HNP_PATH}/../${HNP_TOOL}pack-i${LIBZIP_INSTALL_HNP_PATH}-o${ARCHIVE_PATH}/tar-zvcf${ARCHIVE_PATH}/ohos_${component_name}_${component_version}.tar.gz${component_name}_${component_version}/popd构建与打包流程生成 HNP 产物并输出安装包进入本地 build 目录执行主构建脚本 build.sh 并传入鸿蒙 SDK 的 Linux 版本路径触发 libzip 针对鸿蒙系统的完整构建流程生成适配的构建产物cd~/build ./build.sh--sdk~/ohos-sdk/linux推送至 GitCode开源共建及远程仓库维护流程1、GitCode 创建代码仓库2、本地 Git 关联远程仓库可能会报错错误是 Git 的安全机制检测到仓库目录的所有者有问题因为是 WSL 跨系统目录按照提示添加安全目录例外即可gitconfig--global--addsafe.directory%(prefix)///wsl$/Ubuntu-24.04/home/weishuo/build/code/libzip3、拉取远程 main 分支同步# 拉取远程main分支到本地如果本地没有main分支会自动创建gitpull origin main4、暂存所有本地修改和未追踪文件# 暂存所有本地修改android/do.sh 等 未追踪的 hnp.jsongitadd.# 验证确认无未合并路径、所有修改已暂存gitstatus5、完成合并提交gitcommit-m合并远程main分支以本地代码为主覆盖README.md冲突6、强制推送本地代码到远程git push -u origin main --forcelibzip 鸿蒙构建安装错误解决方案总览错误现象描述在鸿蒙系统上构建 libzip 1.11.4 时安装阶段出现以下错误Unknown argument -- Usage: cmake --install dir [options] ...错误原因定位与触发点分析错误发生在构建脚本的安装命令中${CMAKE}--install.--prefix${install_prefix}--DESTDIR${LIBZIP_INSTALL_HNP_PATH}CMake 3.20 版本不再接受 – DESTDIR 这种参数传递方式最终解决方案修改文件code/libzip/build_ohos.sh修改行号第 48 行修改前错误${CMAKE}--install.--prefix${install_prefix}--DESTDIR${LIBZIP_INSTALL_HNP_PATH}修改后正确DESTDIR${LIBZIP_INSTALL_HNP_PATH}${CMAKE}--install.--prefix${install_prefix}修改说明将 DESTDIR 从命令行参数改为环境变量删除无效的 – 分隔符保持其他参数不变构建结果验证方法执行构建脚本后检查 libzip 是否成功安装到指定目录# 查看安装目录ls-la${LIBZIP_INSTALL_HNP_PATH}# 检查库文件ls-la${LIBZIP_INSTALL_HNP_PATH}/usr/local/lib/*.a构建与安装的注意事项此修改只影响CMake 3.20 版本的构建编译过程中的 “warning: argument unused during compilation” 是无害警告不影响最终结果修改后的命令遵循 CMake 官方推荐的环境变量传递方式这个解决方案已在实际的鸿蒙系统构建中验证通过能够成功完成 libzip 的构建和安装欢迎加入开源鸿蒙PC社区https://harmonypc.csdn.net/GitCode代码仓库https://gitcode.com/weixin_62765017/libzip常见问题FAQQ1CMake 报错 Unknown argument – 如何解决原因CMake 3.20 不支持 – DESTDIR 写法解决将 DESTDIR 放到命令前作为环境变量。Q2编译提示 Could NOT find ZLIB 缺失依赖原因鸿蒙交叉编译环境未找到 zlib 库。解决在 CMake 中关闭不必要模块或先完成 zlib 鸿蒙适配。Q3生成的库在鸿蒙上无法链接使用原因架构不匹配或未使用鸿蒙 sysroot 工具链编译。解决确认 --targetaarch64-linux-ohos使用鸿蒙 SDK 里的 clang、ld.lld。真机测试执行zipcmp -h、ziptool -h、zipmerge -h三条命令均成功输出对应工具的帮助信息说明 libzip 库及配套工具在鸿蒙真机上部署正常、可正常运行测试验证成功# 查看 ZIP 对比工具的帮助说明zipcmp-h# 查看 ZIP 操作工具的帮助说明ziptool-h# 查看 ZIP 合并工具的帮助说明zipmerge-h