[鸿蒙PC命令行移植适配]移植rust三方库envfetch到鸿蒙PC的完整实践

$鸿蒙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/159284830
`Windows 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/154794871
OpenHarmony Linux 命令行工具适配实战：基于 `Cursor × WSL` 的 `tree 2.2.1` 交叉编译与 `HNP` 打包全流程指南	https://weishuo.blog.csdn.net/article/details/155140843
社区维护的鸿蒙 PC 生态命令行工具构建框架 `lycium_plusplus`	https://atomgit.com/OpenHarmonyPCDeveloper/lycium_plusplus
支持Rust三方库适配的扩展lycium框架	https://atomgit.com/CodexBai/lycium_plusplus.git
鸿蒙PC端二进制文件签名命令行使用指南	https://blog.csdn.net/jianguo888888/article/details/156644386
`hnp`包验证环境	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 的压缩包。

bash 复制代码

# Linux / macOS 示例（包名以 DCP 页面为准）
# 个人建议下载目录为 ~/ohos-sdk
mkdir -p ~/ohos-sdk
tar -xzf ohos-sdk-mac-*.tar.gz -C ~/ohos-sdk/

注意：解压后请确认 SDK 目录中包含 ohos-sdk 文件夹。如果 SDK 下载失败或希望快速体验，可以只安装 ohos-sdk 中的 native 工具链（约 2GB），不影响 Rust 交叉编译流程。

1.2 SDK 目录结构

解压后，SDK 的目录结构如下：

text 复制代码

~/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/   # 公开 SDK（Java/JS 等）
│       └── ...

1.3 环境变量配置

将 SDK 路径添加到 ~/.zshrc 或 ~/.bash_profile 中：

bash 复制代码

# OpenHarmony SDK 路径
export OHOS_SDK_HOME=~/ohos-sdk/ohos-sdk/6.0.0.152
export OHOS_NATIVE_HOME=$OHOS_SDK_HOME/native

# 添加到 PATH
export PATH=$OHOS_NATIVE_HOME/llvm/bin:$PATH
export PATH=$OHOS_NATIVE_HOME/build-tools/ohos-build-tools/bin:$PATH

# 验证
echo "OHOS_SDK_HOME=$OHOS_SDK_HOME"

说明：请根据实际下载的 SDK 版本号（如 6.0.0.152）替换路径中的版本号。

使环境变量生效：

bash 复制代码

source ~/.zshrc  # 或 source ~/.bash_profile

1.4 验证 SDK 配置

配置完成后，执行以下命令验证 SDK 是否配置正确：

bash 复制代码

# 检查 SDK 路径
echo $OHOS_NATIVE_HOME

# 检查工具是否在 PATH 中
which clang
which clang++

# 检查 SDK 工具目录
ls $OHOS_NATIVE_HOME/build-tools/ohos-build-tools/bin/

# 验证工具版本
clang --target=aarch64-linux-ohos --sysroot=$OHOS_NATIVE_HOME/sysroot --version

如果能够正常显示 clang 版本信息（且 target 中包含 aarch64-linux-ohos），说明 SDK 环境配置成功。

2 Rust 工具链安装

envfetch 使用 Rust 语言开发，因此需要安装 Rust 工具链来完成交叉编译。

2.1 安装 Rust

如果尚未安装 Rust，可以使用以下命令进行安装：

bash 复制代码

# 安装 Rust（如果未安装）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 验证安装
rustc --version
cargo --version

2.2 配置 Rust 环境变量

bash 复制代码

# Rust 环境变量（通常由 rustup 自动添加）
export PATH=$HOME/.cargo/bin:$PATH

# 验证
rustc --version
cargo --version

确保 Rust 版本 >= 1.70，以支持 edition = "2024"（envfetch 使用 edition = "2024"，或降级为 2021 编译）。

使环境变量生效：

bash 复制代码

source ~/.zshrc  # 或 source ~/.bash_profile
rustc --version
cargo --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，也可以执行以下命令进行创建。

shell 复制代码

# 我将交叉编译框架克隆在根目录，此处可改为正确的目录地址
cd ~/lycium_plusplus/RustAdapt
mkdir ohos-envfetch

3. 编写`HPKBUILD`

然后将lycium/template/HPKBUILD.cargo拷贝到RustAdapt/ohos-envfetch目录下，并重命名为HPKBUILD，HPKBUILD是lycium交叉编译框架完成编译构建的核心配置文件，定义包的元信息、依赖、构建和打包逻辑。需要根据模板在HPKBUILD开头声明envfetch的基本信息，这些字段被lycium用于下载、组织和记录：

bash 复制代码

# lycium_plusplus/RustAdapt/ohos-envfetch/HPKBUILD
pkgname=envfetch # 库名
pkgver=2.1.2 # 库版本
pkgrel=0 # 发布号
pkgdesc="Lightweight cross-platform CLI tool for working with environment variables" # 库描述
url="https://github.com/ankddev/envfetch" # 官网链接
archs=("arm64-v8a") # cpu 架构
license=("MIT")
depends=() # 依赖库的目录名 必须保证被依赖的库的archs是当前库的archs的超集
makedepends=("cargo" "rustc") # 构建库时的依赖工具->需要用户安装的工具
source="https://github.com/ankddev/envfetch/archive/refs/tags/v${pkgver}.tar.gz" # 库源码下载链接

downloadpackage=true # 是否自动下载压缩包，如若不写默认 true. (应对一些特殊情况，代码只能 git clone (项目中依赖 submoudle ))
autounpack=true # 是否自动解压，如若不写默认 true, 如果为 false 则需要用户在 prepare 函数中自行解压
buildtools=cargo # 编译方法: cmake(默认) | configure | cargo | 其它则不在此注入 buildargs，由 build() 自行处理

builddir=envfetch-${pkgver} # 源码压缩包解压后目录名 编译目录名
packagename=$builddir.tar.gz # 压缩包名

字段	配置值	用途
`pkgname`	`envfetch`	`pkgname=envfetch`：包名，用于在 `LYCIUM_ROOT/usr/` 下创建安装目录、标识依赖关系。
`pkgver`	`2.1.2`	`pkgver=2.1.2`：上游版本号，与 `https://github.com/ankddev/envfetch` 仓库最新发行版本保持一致。
`pkgrel`	`0`	`pkgrel=0`：包发布号，当同一上游版本需要重新打包时递增，首次适配为 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` 工具链是编译前提。
`source`	`refs/tags/v${pkgver}.tar.gz`	源码包下载地址。使用 `${pkgver}` 变量拼接，下载 `envfetch 2.1.2` 的 `release tarball`（注意标签含 `v` 前缀）。
`downloadpackage`	`true`	`downloadpackage=true`：告诉 `lycium` 构建系统自动下载 `source` 指定的源码包。如果设置为`false`需要在目标库目录下手动下载源码包。
`autounpack`	`true`	`autounpack=true`：下载后自动解压，无需手动解压步骤。如果设置为`false`需要手动解压。
`buildtools`	`cargo`	`buildtools=cargo`：声明构建工具类型。`lycium` 据此选择 `Cargo` 构建流程（而非 `make/cmake` 等）。
`builddir`	`envfetch-${pkgver}`	`builddir=envfetch-${pkgver}`：解压后的源码目录名。`prepare()`/`build()`/`package()` 均通过 `cd $builddir` 进入此目录。
`packagename`	`${builddir}.tar.gz`	`packagename=${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并复制到安装目录。

sh 复制代码

# 打包安装
package() {
    # 进入 Rust 项目目录（和编译时同一个目录）
    cd $builddir
    # 定义安装路径：鸿蒙库的安装目录
    DEST="$LYCIUM_ROOT/usr/$pkgname/$ARCH"
    # 创建安装目录bin 文件夹
    mkdir -p $DEST/bin/
    # 【关键】把编译好的 Rust 程序 → 复制到目标目录的 bin 文件夹
    cp target/${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 打包，详细介绍可参考系列索引-构建执行与产物获取。

json 复制代码

{
    "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签名授权。

sh 复制代码

# 进入envfetch所在目录
cd Desktop
# 执行签名
binary-sign-tool sign -inFile envfetch -outFile envfetch -selfSign "1"
# 授予权限
chmod +x envfetch
# 查看envfetch版本
./envfetch --version
# 查看envfetch帮助
./envfetch --help
# 获取指定环境变量值
./envfetch get PATH

四、 FAQ

执行签名命令出现"zsh: command not found: binary-sign-tool"提示。

这个是因为binary-sign-tool是鸿蒙PC命令行签名工具，需要在鸿蒙PC上安装该工具。该工具由于目前没有上架包管理器，需要前往《鸿蒙PC端二进制文件签名命令行使用指南》获取安装方式。

[鸿蒙PC命令行移植适配]移植rust三方库envfetch到鸿蒙PC的完整实践