[鸿蒙PC命令行移植适配]移植rust三方库envfetch到鸿蒙PC的完整实践欢迎加入【开源鸿蒙PC社区】一起共建鸿蒙化C/C三方库生态。前言envfetch是由 ANKDDEV 开发的跨平台环境变量管理工具采用 Rust 语言编写。它能让你轻松查看、获取、设置、删除和导出环境变量支持临时当前会话和永久写入 Shell 配置文件两种模式。envfetch 还内置交互式 TUI 模式基于 ratatui支持从 dotenv 文件批量加载变量、模糊搜索相似变量名、以及通过配置文件自定义行为是日常开发和运维管理环境变量的得力工具。前置条件环境/工具描述适配库envfetch开源协议MIT源码版本2.1.2目标平台鸿蒙PC依赖项无操作系统平台macOS原仓库地址https://github.com/ankddev/envfetch鸿蒙化适配仓库地址https://atomgit.com/OpenHarmonyPCDeveloper/ohos-envfetch在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 安装首先我们需要准备好 OpenHarmony SDK这是交叉编译的基础。可以参考开源鸿蒙SDK的安装与配置文档包含 Linux、macOS、Windows 的安装方式按照当前操作系统选择下载。1.1 下载 SDK环境搭建在开始之前请先确保你的开发环境满足以下要求操作系统macOS本文以 macOS 为例Linux/Windows 操作类似已安装wget或curl下载工具存储空间建议至少 20GB 可用空间SDK 解压后约 15GB前往 OpenHarmony SDK 下载页面 选择对应版本进行下载。提示推荐下载ohos-sdk-windows_linux-mac版本其中包含完整工具链。下载时间因网络而异SDK 约 10GB 下载完成后得到一个类似ohos-sdk-mac-v6.0.0.152.tar.gz的压缩包。# Linux / macOS 示例包名以 DCP 页面为准# 个人建议下载目录为 ~/ohos-sdkmkdir-p~/ohos-sdktar-xzfohos-sdk-mac-*.tar.gz-C~/ohos-sdk/注意解压后请确认 SDK 目录中包含ohos-sdk文件夹。如果 SDK 下载失败或希望快速体验可以只安装ohos-sdk中的 native 工具链约 2GB不影响 Rust 交叉编译流程。1.2 SDK 目录结构解压后SDK 的目录结构如下~/ohos-sdk/ ├── ohos-sdk/ # SDK 根目录 │ └── 6.0.0.152/ # 版本号目录以实际为准 │ ├── native/ # Native 工具链编译所需 │ │ ├── build-tools/ │ │ ├── llvm/ # LLVM 工具链clang, lld 等 │ │ ├── sysroot/ # 系统根目录arm64-v8a, armeabi-v7a, x86_64 │ │ └── ... │ ├── public-sdk/ # 公开 SDKJava/JS 等 │ └── ...1.3 环境变量配置将 SDK 路径添加到~/.zshrc或~/.bash_profile中# OpenHarmony SDK 路径exportOHOS_SDK_HOME~/ohos-sdk/ohos-sdk/6.0.0.152exportOHOS_NATIVE_HOME$OHOS_SDK_HOME/native# 添加到 PATHexportPATH$OHOS_NATIVE_HOME/llvm/bin:$PATHexportPATH$OHOS_NATIVE_HOME/build-tools/ohos-build-tools/bin:$PATH# 验证echoOHOS_SDK_HOME$OHOS_SDK_HOME说明请根据实际下载的 SDK 版本号如 6.0.0.152替换路径中的版本号。使环境变量生效source~/.zshrc# 或 source ~/.bash_profile1.4 验证 SDK 配置配置完成后执行以下命令验证 SDK 是否配置正确# 检查 SDK 路径echo$OHOS_NATIVE_HOME# 检查工具是否在 PATH 中whichclangwhichclang# 检查 SDK 工具目录ls$OHOS_NATIVE_HOME/build-tools/ohos-build-tools/bin/# 验证工具版本clang--targetaarch64-linux-ohos--sysroot$OHOS_NATIVE_HOME/sysroot--version如果能够正常显示clang版本信息且 target 中包含aarch64-linux-ohos说明 SDK 环境配置成功。2 Rust 工具链安装envfetch使用 Rust 语言开发因此需要安装 Rust 工具链来完成交叉编译。2.1 安装 Rust如果尚未安装 Rust可以使用以下命令进行安装# 安装 Rust如果未安装curl--protohttps--tlsv1.2-sSfhttps://sh.rustup.rs|sh# 验证安装rustc--versioncargo--version2.2 配置 Rust 环境变量# Rust 环境变量通常由 rustup 自动添加exportPATH$HOME/.cargo/bin:$PATH# 验证rustc--versioncargo--version确保 Rust 版本 1.70以支持edition 2024envfetch 使用edition 2024或降级为2021编译。使环境变量生效source~/.zshrc# 或 source ~/.bash_profilerustc--versioncargo--version二、适配步骤1. 分析envfetch构建特性envfetch由Rust语言编写使用Cargo作为构建系统。编译后产出的二进制命令为envfetch在Cargo.toml的[package]中name envfetch定义。核心特性查看和搜索环境变量​ 通过envfetch list列出当前所有环境变量及其值使用envfetch get NAME获取指定变量的值若变量不存在会自动提示相似变量名基于 similar-string 库的模糊匹配。设置和修改变量​ 使用envfetch set KEY VALUE设置环境变量支持--permanent参数将变量永久写入 Shell 配置文件.zshrc/.bashrc等不带该参数则仅在当前会话生效。同时支持envfetch append KEY VALUE在变量值末尾追加字符串。删除环境变量​ 使用envfetch delete KEY删除指定变量同样支持--permanent参数实现永久删除。从 dotenv 文件加载​ 使用envfetch load .env从 dotenv 格式文件中批量加载环境变量支持临时加载和永久写入两种模式。导出环境变量​ 使用envfetch export将当前环境变量导出为 Shell 脚本格式或 dotenv 格式方便在不同环境间迁移配置。交互式 TUI 模式​ 直接运行envfetch不带子命令进入交互式终端界面基于 ratatui 和 crossterm 构建支持键盘导航、模糊搜索、实时预览变量值提供沉浸式的环境变量管理体验。配置文件支持​ 支持通过~/.config/envfetch/config.toml配置文件自定义行为和默认参数如设置默认的 Shell 配置文件路径、导出格式偏好等。轻量跨平台​ 采用 Rust 编写编译后为单一二进制文件无外部运行时依赖支持 Windows/macOS/Linux 三大平台。2. 创建适配项目参考前置条件列表完成lycium_plusplus交叉框架编译环境搭建以及lycium_plusplus交叉框架代码克隆在lycium_plusplus/RustAdapt创建目标库envfetch适配目录为ohos-envfetch。为什么是ohos-envfetch为了和源库名称做区分表示该库用于ohos设备。ohos-envfetch创建可以借助编辑器工具如VSCode或者使用文件夹在lycium_plusplus/RustAdapt目录下创建目标库适配目录ohos-envfetch也可以执行以下命令进行创建。# 我将交叉编译框架克隆在根目录此处可改为正确的目录地址cd~/lycium_plusplus/RustAdaptmkdirohos-envfetch3. 编写HPKBUILD然后将lycium/template/HPKBUILD.cargo拷贝到RustAdapt/ohos-envfetch目录下并重命名为HPKBUILDHPKBUILD是lycium交叉编译框架完成编译构建的核心配置文件定义包的元信息、依赖、构建和打包逻辑。需要根据模板在HPKBUILD开头声明envfetch的基本信息这些字段被lycium用于下载、组织和记录# lycium_plusplus/RustAdapt/ohos-envfetch/HPKBUILDpkgnameenvfetch# 库名pkgver2.1.2# 库版本pkgrel0# 发布号pkgdescLightweight cross-platform CLI tool for working with environment variables# 库描述urlhttps://github.com/ankddev/envfetch# 官网链接archs(arm64-v8a)# cpu 架构license(MIT)depends()# 依赖库的目录名 必须保证被依赖的库的archs是当前库的archs的超集makedepends(cargorustc)# 构建库时的依赖工具-需要用户安装的工具sourcehttps://github.com/ankddev/envfetch/archive/refs/tags/v${pkgver}.tar.gz# 库源码下载链接downloadpackagetrue# 是否自动下载压缩包如若不写默认 true. (应对一些特殊情况代码只能 git clone (项目中依赖 submoudle ))autounpacktrue# 是否自动解压如若不写默认 true, 如果为 false 则需要用户在 prepare 函数中自行解压buildtoolscargo# 编译方法: cmake(默认) | configure | cargo | 其它则不在此注入 buildargs由 build() 自行处理builddirenvfetch-${pkgver}# 源码压缩包解压后目录名 编译目录名packagename$builddir.tar.gz# 压缩包名字段配置值用途pkgnameenvfetchpkgnameenvfetch包名用于在LYCIUM_ROOT/usr/下创建安装目录、标识依赖关系。pkgver2.1.2pkgver2.1.2上游版本号与https://github.com/ankddev/envfetch仓库最新发行版本保持一致。pkgrel0pkgrel0包发布号当同一上游版本需要重新打包时递增首次适配为 0。pkgdesc-包的简短描述取自envfetch官方Cargo.toml。url-上游项目主页URL。archs(arm64-v8a)archs(arm64-v8a)声明支持的架构数组。此处仅列出arm64-v8a但代码内部实际也处理了armeabi-v7a和x86_64此处是声明主要支持而非仅支持。当前鸿蒙 PC 设备为arm64架构因此必须配置arm64-v8a。license(MIT)envfetch采用MIT协议。depends()无运行时依赖。makedepends(cargo rustc)makedepends(cargo rustc)编译时依赖。Rust工具链是编译前提。sourcerefs/tags/v${pkgver}.tar.gz源码包下载地址。使用${pkgver}变量拼接下载envfetch 2.1.2的release tarball注意标签含v前缀。downloadpackagetruedownloadpackagetrue告诉lycium构建系统自动下载source指定的源码包。如果设置为false需要在目标库目录下手动下载源码包。autounpacktrueautounpacktrue下载后自动解压无需手动解压步骤。如果设置为false需要手动解压。buildtoolscargobuildtoolscargo声明构建工具类型。lycium据此选择Cargo构建流程而非make/cmake等。builddirenvfetch-${pkgver}builddirenvfetch-${pkgver}解压后的源码目录名。prepare()/build()/package()均通过cd $builddir进入此目录。packagename${builddir}.tar.gzpackagename${builddir}.tar.gz源码包文件名用于校验/定位。还需要修改package函数中编译完成后的二进制文件名称envfetch项目编译完成后会产出一个名为envfetch的二进制文件在Cargo.toml的[package]中name envfetch定义此处需要将cp target/${OHOS_RUST_TARGET}/release/xxx改为cp target/${OHOS_RUST_TARGET}/release/envfetch并复制到安装目录。# 打包安装package(){# 进入 Rust 项目目录和编译时同一个目录cd$builddir# 定义安装路径鸿蒙库的安装目录DEST$LYCIUM_ROOT/usr/$pkgname/$ARCH# 创建安装目录bin 文件夹mkdir-p$DEST/bin/# 【关键】把编译好的 Rust 程序 → 复制到目标目录的 bin 文件夹cptarget/${OHOS_RUST_TARGET}/release/envfetch$DEST/bin/cd$OLDPWD}4 HNP 打包配置在lycium_plusplus/RustAdapt/ohos-envfetch目录下创建hnp.json文件因为在HPKBUILD中存在archive函数用于将产物打包为output/arch/pkgname_ver.tar.gz或执行 HNP 打包详细介绍可参考系列索引-构建执行与产物获取。{type:hnp-config,name:envfetch,version:2.1.2,install:{}}5 交叉编译并解决可能存在的问题HPKBUILD中函数不做改变在lycium_plusplus/lycium目录下打开终端工具输入./build.sh ohos-envfetch进行第一次交叉编译。如果提示ALL JOBS DONE!!!表示当前交叉编译没有问题编译后的产物可以在lycium/usr/目录和out/arm64-v8目录下查看。三、 在鸿蒙PC上验证交叉编译后的envfetch命令是否可用将lycium_plusplus/lycium/usr/envfetch/arm64-v8a/bin/envfetch二进制文件传到鸿蒙PC上方式有多种可以通过聊天软件。macos设备可以在App Store下载【鸿蒙星河互联】通过分享方式将envfetch二进制文件发送到鸿蒙PC设备上这种方式需要鸿蒙PC开启华为分享为所有人可见。在鸿蒙PC右下角会弹出接受弹窗选择接受或者另存为接受envfetch二进制文件。接受后的二进制文件是不可以直接运行的哪怕使用chmod x envfetch这种方式授权也是无法运行的。需要给二进制文件进行签名后才可以在鸿蒙 PC 侧执行前涉及二进制签名流程可参考《鸿蒙PC端二进制文件签名命令行使用指南》。打开鸿蒙PC终端输入以下命令为envfetch签名授权。# 进入envfetch所在目录cdDesktop# 执行签名binary-sign-tool sign-inFileenvfetch-outFileenvfetch-selfSign1# 授予权限chmodx envfetch# 查看envfetch版本./envfetch--version# 查看envfetch帮助./envfetch--help# 获取指定环境变量值./envfetch getPATH四、 FAQ执行签名命令出现zsh: command not found: binary-sign-tool提示。这个是因为binary-sign-tool是鸿蒙PC命令行签名工具需要在鸿蒙PC上安装该工具。该工具由于目前没有上架包管理器需要前往《鸿蒙PC端二进制文件签名命令行使用指南》获取安装方式。