欢迎加入【开源鸿蒙PC社区】一起共建鸿蒙化C/C三方库生态。前言ouch是由 ouch-org 团队开发的压缩与解压缩命令行工具全称Obvious Unified Compression Helper直观的统一压缩助手。它旨在提供一种简单、统一的方式来处理多种压缩格式支持 tar、gz、bz2、zst、lz4、xz、lzma、zip、7z、rar 等多种格式之间的相互转换和操作。与传统的压缩工具需要分别记忆不同格式的命令不同ouch 通过智能的文件扩展名检测和统一的命令行接口让用户无需关心底层实现细节即可完成压缩和解压操作是终端环境下文件压缩管理的得力助手。前置条件环境/工具描述适配库ouch开源协议MIT源码版本0.7.1目标平台鸿蒙PC依赖项无操作系统平台macOS原仓库地址https://github.com/ouch-org/ouch鸿蒙化适配仓库地址https://atomgit.com/OpenHarmonyPCDeveloper/ohos-ouch在Ubuntu中搭建鸿蒙PC 三方库交叉编译构建开发环境https://blog.csdn.net/zl392321162/article/details/159284760在macOS中搭建鸿蒙 PC 三方库交叉编译开发环境https://blog.csdn.net/zl392321162/article/details/159284830Windows 10上安装和使用WSL 2、安装Ubuntu 24详细指南https://blog.csdn.net/yyz_1987/article/details/148545443鸿蒙 PC 命令行适配指南Mac 版https://blog.csdn.net/qq_39132095/article/details/154796658鸿蒙 PC 生态三方软件移植开发环境搭建及三方库移植指南https://blog.csdn.net/yyz_1987/article/details/154794871OpenHarmony Linux 命令行工具适配实战基于Cursor × WSL的tree 2.2.1交叉编译与HNP打包全流程指南https://weishuo.blog.csdn.net/article/details/155140843社区维护的鸿蒙 PC 生态命令行工具构建框架lycium_plusplushttps://atomgit.com/OpenHarmonyPCDeveloper/lycium_plusplus支持Rust三方库适配的扩展lycium框架https://atomgit.com/CodexBai/lycium_plusplus.git鸿蒙PC端二进制文件签名命令行使用指南https://blog.csdn.net/jianguo888888/article/details/156644386hnp包验证环境https://bxming.blog.csdn.net/article/details/155073889系列索引篇章标题内容第一篇概述与环境配置Lycium 概念、构建机要求、OHOS SDK 配置第二篇项目结构与适配目录创建目录结构、community vs thirdparty、创建适配目录第三篇HPKBUILD 编写详解元数据字段、过程函数、三种构建系统写法第四篇构建执行与产物获取构建流程、日志分析、多库递归、HAP 集成第五篇流程图与角色职责完整流程图、各角色职责、协作时序第六篇关键注意事项与最佳实践依赖管理、架构超集、日志调试、外部适配仓第七篇快速参考与模板入门步骤、模板、完整案例、检查清单第八篇「番外」扩展lycium框架使其满足rust三方库适配不改变框架原有设计增加Rust三方库适配能力一、环境配置1 OpenHarmony SDK 安装1.1 下载 SDK环境搭建从OpenHarmony 官方首页下载ohos-sdk压缩包步骤省略详情可见前置条件中环境搭建相关文章。SDK 下载注意事项需要注册并登录AtomGit账户才可以下载。使用Mac系统的开发者一定要下载linux版本的 sdk。存放路径不要含有中文字符、空格或特殊字符建议直接放在用户根目录。资源目录中依赖ohos-sdk压缩包解压后请勿移动/删除原始压缩包。1.2 SDK 放置位置接下来我们需要将ohos-sdk解压并放置到适当的位置。以下是适用于Linux和macOS的示例命令# Linux / macOS 示例包名以 DCP 页面为准cd~/tar-xzfohos-sdk-linux-v5.0.0-*.tar.gzmvohos-sdk ohos-sdk# 统一命名为 ohos-sdk1.3 SDK 目录结构解压后 SDK 的目录结构大致如下ohos-sdk/ ├── linux/# 主机平台工具链│ ├── native/# Native 开发相关工具│ │ ├── build-tools/# cmake、ninja 等构建工具│ │ ├── llvm/# LLVM 工具链clang、lld 等│ │ ├── sysroot/# 系统根目录包含 OHOS 头文件和库│ │ ├── nativeapi_syscap_config/ │ │ └──... │ └──... └──...1.4 环境变量配置将 SDK 路径添加到 shell 配置文件如~/.zshrc、~/.bashrc或~/.bash_profile# OpenHarmony SDK 路径exportOHOS_SDK_HOME$HOME/ohos-sdkexportOHOS_NATIVE_HOME$OHOS_SDK_HOME/linux/native# 添加到 PATHexportPATH$OHOS_NATIVE_HOME/build-tools/bin:$OHOS_NATIVE_HOME/llvm/bin:$PATH# 验证source~/.zshrc# 或 source ~/.bashrc1.5 验证 SDK 配置使用以下命令验证 OHOS SDK 是否正确配置# 检查 SDK 路径echo$OHOS_SDK_HOME# 期望输出: /Users/your-username/ohos-sdk# 检查工具是否在 PATH 中whichcmakewhichninja# 期望输出: /Users/your-username/ohos-sdk/linux/native/build-tools/bin/cmake# 期望输出: /Users/your-username/ohos-sdk/linux/native/build-tools/bin/ninja# 检查 SDK 工具目录ls$OHOS_NATIVE_HOME# 期望看到: build-tools llvm sysroot nativeapi_syscap_config 等目录# 验证工具版本cmake--versionninja--version2 Rust 工具链安装Rust工具链的安装方法在所有平台上基本一致关键在于添加正确的 OHOS 目标平台支持。2.1 安装 Rust# 安装 Rust如果未安装curl--protohttps--tlsv1.2-sSfhttps://sh.rustup.rs|sh# 验证安装rustc--version# 应显示 rustc 1.xx.x 或更高版本cargo--version# 应显示 cargo 1.xx.x2.2 添加 OHOS 目标平台# 添加 OHOS 的目标平台支持rustup targetaddaarch64-unknown-linux-ohos2.3 配置 Rust 环境变量# Rust 环境变量通常由 rustup 自动添加exportCARGO_HOME$HOME/.cargoexportPATH$CARGO_HOME/bin:$PATHexportOHOS_RUST_TARGETaarch64-unknown-linux-ohos# 验证source~/.zshrcecho$OHOS_RUST_TARGET# 期望输出: aarch64-unknown-linux-ohos注意实际编译时lycium会自动设置环境变量用户一般无需手动设置。二、适配步骤1. 分析ouch构建特性ouch由Rust语言编写使用Cargo作为构建系统。编译后产出的二进制命令为ouch与包名相同。ouch 的Cargo.toml中default [unrar, use_zlib, use_zstd_thin, bzip3]表示默认启用 RAR、zlib、Zstandard 瘦版和 BZip3 支持。需要注意的是ouch 的默认特性依赖了多个 C 语言库unrar、zlib、zstd、bzip3这些 C 库的源码通过 Rust 的cccrate 在编译时自动编译。由于lycium框架已配置好 OHOS 交叉编译环境CC、CFLAGS等环境变量cccrate 能够正确调用 OHOS 的交叉编译器因此使用默认特性即可完成交叉编译。对于 RAR 格式的unrar依赖如果需要简化构建过程也可以通过--no-default-features --features use_zlib,use_zstd_thin,bzip3禁用它。核心特性统一压缩与解压​ 通过智能的文件扩展名检测自动识别压缩格式并执行相应的压缩或解压操作。用户无需记忆不同工具的命令行参数只需指定源文件和目标文件即可。多格式支持​ 支持 tar、gzgzip、bz2bzip2、xz、lzma、zstzstd、lz4、zip、7z、rar 等多种常见压缩格式以及格式之间的相互转换满足日常文件处理的各种需求。压缩级别控制​ 通过--compression参数灵活控制压缩级别0-9 或具体格式支持的级别范围支持在压缩速度和文件大小之间按需平衡。保留文件权限与时间戳​ 在解压时自动保留源文件的权限、修改时间和创建时间确保文件元数据不丢失适合用于备份和归档场景。并行压缩加速​ 利用rayon并行计算库在多核 CPU 上并行处理文件压缩任务显著提升大规模文件或目录的压缩速度。友好的错误提示与进度显示​ 提供清晰、可读的错误消息在压缩和解压过程中显示文件处理进度帮助用户实时了解操作状态。2. 创建适配项目参考前置条件列表完成lycium_plusplus交叉框架编译环境搭建以及lycium_plusplus交叉框架代码克隆在lycium_plusplus/RustAdapt创建目标库ouch适配目录为ohos-ouch。为什么是ohos-ouch为了和源库名称做区分表示该库用于ohos设备。ohos-ouch创建可以借助编辑器工具如VSCode或者使用文件夹在lycium_plusplus/RustAdapt目录下创建目标库适配目录ohos-ouch也可以执行以下命令进行创建。# 我将交叉编译框架克隆在根目录此处可改为正确的目录地址cd~/lycium_plusplus/RustAdaptmkdirohos-ouch3. 编写HPKBUILD然后将lycium/template/HPKBUILD.cargo拷贝到RustAdapt/ohos-ouch目录下并重命名为HPKBUILDHPKBUILD是lycium交叉编译框架完成编译构建的核心配置文件定义包的元信息、依赖、构建和打包逻辑。需要根据模板在HPKBUILD开头声明ouch的基本信息这些字段被lycium用于下载、组织和记录# lycium_plusplus/RustAdapt/ohos-ouch/HPKBUILDpkgnameouch# 库名pkgver0.7.1# 库版本pkgrel0# 发布号pkgdescA command-line utility for easily compressing and decompressing files and directories.# 库描述urlhttps://github.com/ouch-org/ouch# 官网链接archs(arm64-v8a)# cpu 架构license(MIT)depends()# 依赖库的目录名 必须保证被依赖的库的archs是当前库的archs的超集makedepends(cargorustc)# 构建库时的依赖工具-需要用户安装的工具sourcehttps://github.com/ouch-org/ouch/archive/refs/tags/${pkgver}.tar.gz# 库源码下载链接downloadpackagetrue# 是否自动下载压缩包如若不写默认 true. (应对一些特殊情况代码只能 git clone (项目中依赖 submoudle ))autounpacktrue# 是否自动解压如若不写默认 true, 如果为 false 则需要用户在 prepare 函数中自行解压buildtoolscargo# 编译方法: cmake(默认) | configure | cargo | 其它则不在此注入 buildargs由 build() 自行处理builddirouch-${pkgver}# 源码压缩包解压后目录名 编译目录名packagename$builddir.tar.gz# 压缩包名注意ouch 的 GitHub 标签采用数字版本号格式0.7.1不带v前缀。因此source字段中${pkgver}前不加v与常见的v${pkgver}格式不同。字段配置值用途pkgnameouchpkgnameouch包名用于在LYCIUM_ROOT/usr/下创建安装目录、标识依赖关系。pkgver0.7.1pkgver0.7.1上游版本号与https://github.com/ouch-org/ouch仓库最新发行版本保持一致。pkgrel0pkgrel0包发布号当同一上游版本需要重新打包时递增首次适配为 0。pkgdesc-包的简短描述取自ouch官方README。url-上游项目主页URL。archs(arm64-v8a)archs(arm64-v8a)声明支持的架构数组。此处仅列出arm64-v8a但代码内部实际也处理了armeabi-v7a和x86_64此处是声明主要支持而非仅支持。当前鸿蒙 PC 设备为arm64架构因此必须配置arm64-v8a。license(MIT)ouch采用MIT协议。depends()无运行时依赖。makedepends(cargo rustc)makedepends(cargo rustc)编译时依赖。Rust工具链是构建前提。sourcetags/${pkgver}.tar.gz源码包下载地址。使用${pkgver}变量拼接下载ouch 0.7.1的release tarball注意标签不带v前缀。downloadpackagetruedownloadpackagetrue告诉lycium构建系统自动下载source指定的源码包。如果设置为false需要在目标库目录下手动下载源码包。autounpacktrueautounpacktrue下载后自动解压无需手动解压步骤。如果设置为false需要手动解压。buildtoolscargobuildtoolscargo声明构建工具类型。lycium据此选择Cargo构建流程而非make/cmake等。builddirouch-${pkgver}builddirouch-${pkgver}解压后的源码目录名。prepare()/build()/package()均通过cd $builddir进入此目录。packagename${builddir}.tar.gzpackagename${builddir}.tar.gz源码包文件名用于校验/定位。package函数中编译完成后的二进制文件名称与包名一致ouch项目编译完成后会产出一个名为ouch的二进制文件此处需要将cp target/${OHOS_RUST_TARGET}/release/xxx改为cp target/${OHOS_RUST_TARGET}/release/ouch并复制到安装目录。# 打包安装package(){# 进入 Rust 项目目录和编译时同一个目录cd$builddir# 定义安装路径鸿蒙库的安装目录DEST$LYCIUM_ROOT/usr/$pkgname/$ARCH# 创建安装目录bin 文件夹mkdir-p$DEST/bin/# 【关键】把编译好的 Rust 程序 → 复制到目标目录的 bin 文件夹cptarget/${OHOS_RUST_TARGET}/release/ouch$DEST/bin/cd$OLDPWD}4 HNP 打包配置在lycium_plusplus/RustAdapt/ohos-ouch目录下创建hnp.json文件因为在HPKBUILD中存在archive函数用于将产物打包为output/arch/pkgname_ver.tar.gz或执行 HNP 打包详细介绍可参考系列索引-构建执行与产物获取。{type:hnp-config,name:ouch,version:0.7.1,install:{}}5 交叉编译并解决可能存在的问题HPKBUILD中函数不做改变在lycium_plusplus/lycium目录下打开终端工具输入./build.sh ohos-xh进行第一次交叉编译。构建失败ouch依赖unrar→unrar_sys会编译 C 并打成静态库。最终链接时命令里会出现-lstdc来自rustc对“含 C 对象”的默认处理而不是unrar_sys的build.rs显式写的于是报错ld.lld: error: unable tofindlibrary -lstdcouch默认启用unrarCargo.toml的default [unrar, ...]unrar_sys在编译 RAR 的 C 代码时经cccrate 把-lstdc写进 rlib 元数据而 OHOS SDK只有 libclibc.so等没有 libstdc在lycium/script/build_hpk.sh的cargodependpath()里已设置交叉链接器但未指定 OHOS 的 C 标准库名。在lycium/script/build_hpk.sh的cargodependpath()里告诉cccrate各*-sys的build.rs里编译 C/C 时用链接时使用libc而不是默认的libstdc。# Rust(cargo)为 depends 拼接 pkg-config / OpenSSL 路径并设置 OHOS 交叉链接器与 C/C 编译环境供 build.rs/cc-rscargodependpath(){buildargspkgconfigpathunsetCARGO_TARGET_AARCH64_UNKNOWN_LINUX_OHOS_LINKER CARGO_TARGET_ARMV7_UNKNOWN_LINUX_OHOS_LINKER CARGO_TARGET_X86_64_UNKNOWN_LINUX_OHOS_LINKER2/dev/nullunsetCARGO_TARGET_AARCH64_UNKNOWN_LINUX_OHOS_RUSTFLAGS CARGO_TARGET_ARMV7_UNKNOWN_LINUX_OHOS_RUSTFLAGS CARGO_TARGET_X86_64_UNKNOWN_LINUX_OHOS_RUSTFLAGS2/dev/nullunsetCXXSTDLIB OPENSSL_DIR OPENSSL_LIB_DIR OPENSSL_INCLUDE_DIR2/dev/nullif[${#depends[]}-ne0]thenfordependin${depends[]}dodependpath$LYCIUM_ROOT/usr/$depend/$1/lib/pkgconfigif[-d${dependpath}]thenpkgconfigpath$pkgconfigpath${dependpath}:ficase$dependinopenssl|openssl111)if[-d$LYCIUM_ROOT/usr/$depend/$1]thenexportOPENSSL_DIR$LYCIUM_ROOT/usr/$depend/$1exportOPENSSL_LIB_DIR$OPENSSL_DIR/libexportOPENSSL_INCLUDE_DIR$OPENSSL_DIR/includefi;;esacdonepkgconfigpath${pkgconfigpath%:*}fiif[-n$pkgconfigpath]thenexportPKG_CONFIG_PATH$pkgconfigpathexportPKG_CONFIG_ALLOW_CROSS1elseunsetPKG_CONFIG_PATHficase$1inarm64-v8a)exportOHOS_RUST_TARGETaarch64-unknown-linux-ohos;;armeabi-v7a)exportOHOS_RUST_TARGETarmv7-unknown-linux-ohos;;x86_64)exportOHOS_RUST_TARGETx86_64-unknown-linux-ohos;;*)echocargodependpath: unknown ARCH$1;return1;;esacif[-f${LYCIUM_ROOT}/script/envset.sh]then# shellcheck sourceenvset.sh.${LYCIUM_ROOT}/script/envset.shif[-n${TARGET_HARMONYOS}][$1arm64-v8a]thensetHarmonyOSENVexportCARGO_TARGET_AARCH64_UNKNOWN_LINUX_OHOS_LINKER${CC:-clang}elsecase$1inarmeabi-v7a)setarm32ENV;;arm64-v8a)setarm64ENV;;x86_64)setx86_64ENV;;esacif[-n$OHOS_SDK][-d$OHOS_SDK/native/llvm/bin]thencase$1inarm64-v8a)exportCARGO_TARGET_AARCH64_UNKNOWN_LINUX_OHOS_LINKER$OHOS_SDK/native/llvm/bin/aarch64-linux-ohos-clang;;armeabi-v7a)exportCARGO_TARGET_ARMV7_UNKNOWN_LINUX_OHOS_LINKER$OHOS_SDK/native/llvm/bin/arm-linux-ohos-clang;;x86_64)exportCARGO_TARGET_X86_64_UNKNOWN_LINUX_OHOS_LINKER$OHOS_SDK/native/llvm/bin/x86_64-linux-ohos-clang;;esacelsecase$1inarm64-v8a)exportCARGO_TARGET_AARCH64_UNKNOWN_LINUX_OHOS_LINKER${CC:-clang};;armeabi-v7a)exportCARGO_TARGET_ARMV7_UNKNOWN_LINUX_OHOS_LINKER${CC:-clang};;x86_64)exportCARGO_TARGET_X86_64_UNKNOWN_LINUX_OHOS_LINKER${CC:-clang};;esacfi# OHOS 使用 libcrustc 链接含 C 静态库时仍会注入 -lstdc需改链 libc 并提供兼容符号exportCXXSTDLIBcif[-n$OHOS_SDK]thencase$1inarm64-v8a)_ohos_rust_tripleaarch64-linux-ohos_ohos_rust_libdir${OHOS_SDK}/native/llvm/lib/${_ohos_rust_triple}_ohos_rust_linkhack${LYCIUM_ROOT}/tmp/ohos-rust-link/${_ohos_rust_triple}mkdir-p${_ohos_rust_linkhack}ln-sf${_ohos_rust_libdir}/libc.so${_ohos_rust_linkhack}/libstdc.soexportCARGO_TARGET_AARCH64_UNKNOWN_LINUX_OHOS_RUSTFLAGS-L${_ohos_rust_linkhack}-L${_ohos_rust_libdir}-C link-arg-lc;;armeabi-v7a)_ohos_rust_triplearm-linux-ohos_ohos_rust_libdir${OHOS_SDK}/native/llvm/lib/${_ohos_rust_triple}_ohos_rust_linkhack${LYCIUM_ROOT}/tmp/ohos-rust-link/${_ohos_rust_triple}mkdir-p${_ohos_rust_linkhack}ln-sf${_ohos_rust_libdir}/libc.so${_ohos_rust_linkhack}/libstdc.soexportCARGO_TARGET_ARMV7_UNKNOWN_LINUX_OHOS_RUSTFLAGS-L${_ohos_rust_linkhack}-L${_ohos_rust_libdir}-C link-arg-lc;;x86_64)_ohos_rust_triplex86_64-linux-ohos_ohos_rust_libdir${OHOS_SDK}/native/llvm/lib/${_ohos_rust_triple}_ohos_rust_linkhack${LYCIUM_ROOT}/tmp/ohos-rust-link/${_ohos_rust_triple}mkdir-p${_ohos_rust_linkhack}ln-sf${_ohos_rust_libdir}/libc.so${_ohos_rust_linkhack}/libstdc.soexportCARGO_TARGET_X86_64_UNKNOWN_LINUX_OHOS_RUSTFLAGS-L${_ohos_rust_linkhack}-L${_ohos_rust_libdir}-C link-arg-lc;;esacfififireturn0}如果提示ALL JOBS DONE!!!表示当前交叉编译没有问题编译后的产物可以在lycium/usr/目录和out/arm64-v8目录下查看。三、 在鸿蒙PC上验证交叉编译后的ouch命令是否可用将lycium_plusplus/lycium/usr/ouch/arm64-v8a/bin/ouch二进制文件传到鸿蒙PC上方式有多种可以通过聊天软件。macos设备可以在App Store下载【鸿蒙星河互联】通过分享方式将ouch二进制文件发送到鸿蒙PC设备上这种方式需要鸿蒙PC开启华为分享为所有人可见。在鸿蒙PC右下角会弹出接受弹窗选择接受或者另存为接受ouch二进制文件。接受后的二进制文件是不可以直接运行的哪怕使用chmod x ouch这种方式授权也是无法运行的。需要给二进制文件进行签名后才可以在鸿蒙 PC 侧执行前涉及二进制签名流程可参考《鸿蒙PC端二进制文件签名命令行使用指南》。打开鸿蒙PC终端输入以下命令为ouch签名授权。# 进入ouch所在目录cdDesktop# 执行签名binary-sign-tool sign-inFileouch-outFileouch-selfSign1# 授予权限chmodx ouch# 查看ouch版本./ouch--version# 使用 ouch 压缩文件echohello ouchtest.txt./ouch compress test.txt test.tar.gz# 使用 ouch 解压文件./ouch decompress test.tar.gz四、 FAQ执行签名命令出现“zsh: command not found: binary-sign-tool”提示。需要在应用市场搜索DevBox并安装DevBox提供了一些开发者常用命令主要包含文件和目录操作命令、网络命令、构建命令、签名工具等。