【鸿蒙PC命令行适配】rust应用交叉编译环境搭建和bat命令的移植实战指南

一、前言

Rust语言因其内存安全、高效性能和零成本抽象的特点，使得用它开发的命令行工具在性能、安全性和跨平台性方面表现出色。如今，已有许多知名的Rust命令行工具，如bat：它可以替代cat命令，支持语法高亮。

随着鸿蒙PC生态系统的不断成熟，越来越多开发者想要将高性能的Rust应用程序迁移到鸿蒙PC上。然而，目前鸿蒙PC不支持像apt或brew这样的包管理器，也没有原生支持Rust开发的环境。对于希望在鸿蒙PC上运行Rust应用的开发者来说，就需要自行编译构建，这个过程中的主要挑战在于配置Rust的交叉编译环境。由于鸿蒙PC采用aarch64架构并基于OpenHarmony内核，因此其编译工具链与常见的Linux/x86系统有所不同，需要特别设置。

本文将以Ubuntu 24.04为示例操作系统，按照鸿蒙SDK的标准步骤，指导读者从准备环境开始，经过工具链配置、编译测试直到故障排查，一步步完成针对鸿蒙PC平台的Rust应用交叉编译环境搭建过程。

二、前置知识与环境要求

2.1 核心概念

交叉编译：在x86_64 Linux主机（本文以Ubuntu 24.04为例）编译出能在鸿蒙PC（aarch64/arm64架构，OpenHarmony内核）运行的Rust二进制程序。
目标三元组 ：鸿蒙PC的Rust目标架构标识为aarch64-unknown-linux-ohos（OpenHarmony专属），Rust官方已支持该目标，需通过鸿蒙SDK提供的工具链完成链接适配。
工具链依赖：鸿蒙SDK内置llvm、clang、ld.lld等全套交叉编译工具，无需额外安装第三方aarch64-gcc工具链。

2.2 环境要求

环境/工具	版本要求	作用
主机系统	Ubuntu 24.04（x86_64）	交叉编译宿主环境
Rust环境	rustup、cargo、rustc	Rust核心编译工具
鸿蒙SDK	OpenHarmony 6.0+	提供鸿蒙PC的交叉工具链和系统库
依赖工具	git、make、cmake、pkg-config、unzip	基础编译与解压依赖

三、环境搭建步骤

3.1 安装Ubuntu 24.04

我是在Windows系统上，使用wsl安装的Ubuntu 24.04，具体安装过程不再赘述，大家可参考这篇博客：《在 Windows 10 上安装和使用 WSL 2 安装 Ubuntu24详细指南》。大家根据自己的关系，也可以使用虚拟机甚至是云主机等来安装Ubuntu 24.04。

3.2 安装基础依赖

首先安装Ubuntu系统层面的基础依赖，避免后续工具链配置和源码编译时出现命令缺失：

md-end-block 复制代码

# 更新软件源
sudo apt update

# 安装核心基础依赖
sudo apt install -y curl git vim make cmake pkg-config unzip python3 python3-pip build-essential libssl-dev libclang-dev

3.3 配置Rust基础环境

3.3.1 安装rustup

先通过rustup --version命令查看是否已经安装rustup命令。如果已经安装过rustup，则忽略本小节（3.3.1）内容，直接看《3.3.2 添加鸿蒙PC目标架构》。

如果未安装rustup则参考下面步骤中的命令，逐一执行：

md-end-block 复制代码

# 国内用户优先配置清华镜像加速（避免下载慢）
export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup
export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup

# 执行官方一键安装脚本
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

出现如上图所示的提示时，直接按回车键确认。

如上图所示，表面安装成功。根据提示，要在当前终端使用rust工具，还需要执行source位于$HOME/.cargo目录下的env文件。命令为

md-end-block 复制代码

. $HOME/.cargo/env

然后执行rustup --version && cargo --version && rustc --version命令验证rust工具集是否可以顺利执行。

如上图所示，顺利得到rustup、cargo、rustc三个工具的版本号，说明rust工具集顺利执行，安装成功。

补充说明一下：rustup安装完成后新启动的shell会自动执行. $HOME/.cargo/env命令，无需每次手动执行。

3.3.2 添加鸿蒙PC目标架构

要构建鸿蒙PC版本的rust应用，需要添加一个鸿蒙PC专属的目标架构：aarch64-unknown-linux-ohos目标，可直接通过rustup添加：

md-end-block 复制代码

# 添加鸿蒙PC专属目标架构
rustup target add aarch64-unknown-linux-ohos

# 验证目标是否安装成功
rustup target list | grep aarch64-unknown-linux-ohos

如上图所示，输出 aarch64-unknown-linux-ohos (installed) 则说明添加成功。

3.4 下载并配置鸿蒙SDK

鸿蒙SDK是交叉编译的核心，需按官方标准流程下载并配置，确保工具链路径和环境变量正确生效：

3.4.1 创建工作目录

为保持文件整洁，统一将SDK和相关工具放在专属工作目录：

md-end-block 复制代码

# 创建鸿蒙PC开发工作目录
mkdir -p ~/harmonypc && cd ~/harmonypc

3.4.2 下载鸿蒙SDK

推荐下载OpenHarmony官方full版本SDK，包含完整的交叉工具链和系统库，可通过官方CI镜像直接下载：

md-end-block 复制代码

# 下载OpenHarmony 6.0+ full版本SDK（20250819构建版，稳定可用）
wget https://cidownload.openharmony.cn/version/Master_Version/ohos-sdk-full_ohos/20250819_020817/version-Master_Version-ohos-sdk-full_ohos-20250819_020817-ohos-sdk-full_ohos.tar.gz

# 解压SDK压缩包（无需指定解压目录，自动生成相关文件）
tar xf version-Master_Version-ohos-sdk-full_ohos-20250819_020817-ohos-sdk-full_ohos.tar.gz

解压后会在当前目录生成ohos-sdk目录，包含SDK核心文件。

3.4.3 解压SDK内置工具链

进入SDK的Linux目录，解压native和toolchains两个关键压缩包（含交叉编译工具链）：

md-end-block 复制代码

# 进入SDK的Linux工具目录
cd ~/harmonypc/ohos-sdk/linux/

# 静默解压native包（含LLVM、Clang等编译工具）
unzip -q native-linux-x64-6.0.0.46-Beta1.zip

# 静默解压toolchains包（含系统库和辅助工具）
unzip -q toolchains-linux-x64-6.0.0.46-Beta1.zip

解压完成后，会在当前目录生成native和toolchains两个目录，其中native/llvm/bin包含核心交叉编译工具。

3.4.4 配置SDK环境变量

需配置编译器、链接器等环境变量，让Rust编译时能找到鸿蒙SDK的工具链，将配置写入shell配置文件，我写好了一键配置命令，可直接复制运行。

md-end-block 复制代码

SHELL_NAME=$(basename $SHELL) && CONFIG_FILE=~/.${SHELL_NAME}rc && echo -e "export OHOS_SDK=~/harmonypc/ohos-sdk/linux\nexport PATH=\${OHOS_SDK}/native/llvm/bin:\${OHOS_SDK}/native/build-tools/cmake/bin:\$PATH\nexport AS=\${OHOS_SDK}/native/llvm/bin/llvm-as\nexport CC=\"\${OHOS_SDK}/native/llvm/bin/clang --target=aarch64-linux-ohos\"\nexport CXX=\"\${OHOS_SDK}/native/llvm/bin/clang++ --target=aarch64-linux-ohos\"\nexport LD=\${OHOS_SDK}/native/llvm/bin/ld.lld\nexport STRIP=\${OHOS_SDK}/native/llvm/bin/llvm-strip\nexport RANLIB=\${OHOS_SDK}/native/llvm/bin/llvm-ranlib\nexport OBJDUMP=\${OHOS_SDK}/native/llvm/bin/llvm-objdump\nexport OBJCOPY=\${OHOS_SDK}/native/llvm/bin/llvm-objcopy\nexport NM=\${OHOS_SDK}/native/llvm/bin/llvm-nm\nexport AR=\${OHOS_SDK}/native/llvm/bin/llvm-ar\nexport CFLAGS=\"-fPIC -D__MUSL__=1\"\nexport CXXFLAGS=\"-fPIC -D__MUSL__=1\"" > ~/.ohos.env && grep -q "# Load OHOS SDK env" $CONFIG_FILE || echo -e "\n# Load OHOS SDK env\nsource ~/.ohos.env" >> $CONFIG_FILE && source ~/.ohos.env && echo "配置完成！OHOS环境变量文件：~/.ohos.env，已添加到 $CONFIG_FILE 自动加载"

3.4.5 验证SDK配置成功

执行以下命令检查编译器是否配置正确：

md-end-block 复制代码

# 查看Clang版本及目标架构
$CC -v

如上图所示，若成功输出包含 Target: aarch64-unknown-linux-ohos 和 OHOS (dev) clang version 15.0.4（或更高版本），就说明鸿蒙SDK工具链配置成功了。

3.5 配置Rust交叉编译规则

创建Rust的全局配置文件，指定aarch64-unknown-linux-ohos目标的链接器和系统库路径，确保编译时能正确关联鸿蒙SDK的资源。注意：文件中的路径必须使用绝对路径，且不可使用环境变量和 **~**。

md-end-block 复制代码

# 创建Cargo配置文件（若已存在则直接编辑）
vim ~/.cargo/config.toml

# 添加以下配置内容，注意修改目录前缀，不支持~和环境变量
[target.aarch64-unknown-linux-ohos]
linker = "/home/gyl/harmonypc/ohos-sdk/linux/native/llvm/bin/clang"
ar = "/home/gyl/harmonypc/ohos-sdk/linux/native/llvm/bin/llvm-ar"

rustflags = [
  "-C", "link-arg=--target=aarch64-linux-ohos",
  "-C", "link-arg=--sysroot=/home/gyl/harmonypc/ohos-sdk/linux/native/sysroot",
  "-C", "link-arg=-L/home/gyl/harmonypc/ohos-sdk/linux/native/sysroot/usr/lib/aarch64-linux-ohos"
]

3.6 rust交叉编译环境验证

通过创建简单的Rust项目，验证交叉编译环境是否正常工作：

3.6.1 创建测试项目

md-end-block 复制代码

# 创建Rust项目
cargo new ohos-pc-rust-demo && cd ohos-pc-rust-demo

# 编写测试代码（验证标准库和系统调用兼容性）
cat > src/main.rs << EOF
fn main() {
    println!("=== Rust App for OpenHarmony PC ===");
    println!("Target Architecture: aarch64-unknown-linux-ohos");
    println!("SDK Path: {}", std::env::var("OHOS_SDK").unwrap_or("Not Configured".to_string()));
    
    // 测试基础数据处理能力
    let numbers = [1, 2, 3, 4, 5];
    let sum: i32 = numbers.iter().sum();
    println!("Sum of [1,2,3,4,5]: {}", sum);
    println!("Cross Compilation Success!");
}
EOF

3.6.2 交叉编译项目

执行以下命令，针对鸿蒙PC目标进行编译：

md-end-block 复制代码

# 编译鸿蒙PC目标（release模式，优化性能）
cargo build --target aarch64-unknown-linux-ohos --release

# 检查编译产物的架构信息
file target/aarch64-unknown-linux-ohos/release/ohos-pc-rust-demo

如上图所示，若file命令输出ELF 64-bit LSB pie executable, ARM aarch64，则说明编译产物为鸿蒙PC所兼容的aarch64架构。

四、bat命令的构建和验证

bat作为高性能的文本查看工具，可以替代系统自带的cat，并增加了对大部分编程语言和标记语言的语法高亮、行号显示等功能，支持Git集成，还能够分页查看长文件。详细介绍可参考官方使用说明。

4.1 源码下载

通过git下载bat源码并切换到v0.26.1版本。

md-end-block 复制代码

# 通过git下载源码
git clone https://atomgit.com/oh-tpc/bat.git

# 切换到最新release版本：v0.26.1
cd bat
git checkout v0.26.1

4.2 构建鸿蒙PC版本

有了前面的经验，构建起bat命令就简单多了，命令如下：

md-end-block 复制代码

# 构建Release版本bat命令
cargo build --target aarch64-unknown-linux-ohos --release

如上图所示，等待构建完成之后，通过file命令查看目标文件：target/aarch64-unknown-linux-ohos/release/bat的格式信息，确实是鸿蒙pc的ARM aarch64架构，说明构建成功。

4.3 鸿蒙pc真机测试

4.3.1 命令传输+自签名

参考文章：《【鸿蒙pc命令行适配】wsl Ubuntu下交叉编译的命令高效传输到鸿蒙pc》的方法，将bat这个文件传输到鸿蒙pc上。

接下来对bat进行自签名并赋予可执行权限。

md-end-block 复制代码

# 自签名
binary-sign-tool sign -inFile bat -outFile bat -selfSign "1"

# 添加可执行权限
chmod +x bat

之后就可以正常运行，使用./bat --version命令可以查询到版本号。

4.3.2 命令测试1：查看python文件

使用bat guess_number.py命令，可以高亮显示文件内容并附带行号。

五、常见问题与解决方案

5.1 编译时提示 "linker not found"

Cargo未找到鸿蒙 SDK 的链接器，链接器未生效或配置路径错误。检查~/.cargo/config.toml置文件中linker路径是否正确，确保其路径指向实际SDK目录。注意使用绝对路径，不支持环境变量，也不支持~ 。

5.2 编译时提示：error[E0463]: can't find crate for `std`

检查~/.cargo/config.toml置文件中的rustflags是否有非法参数，参考3.5节进行修改。

5.3 下载安装Rust速度慢

md-end-block 复制代码

# 国内用户优先配置清华镜像加速（避免下载慢）
export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup
export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup

解决方法：先配置清华镜像源，再下载安装Rustup（3.3.1节已配置）。

六、总结

本文系统性地介绍了在Ubuntu 24.04环境下搭建面向鸿蒙PC平台的Rust交叉编译环境的完整流程。通过合理配置鸿蒙SDK工具链、Rust目标架构以及Cargo编译参数，我们成功实现了从x86_64主机到aarch64-unknown-linux-ohos目标的交叉编译能力。整个环境搭建过程的核心在于正确配置三个关键环节：SDK工具链的路径设置、Rust目标架构的添加，以及Cargo配置文件中链接器和系统库路径的精确指定。

实践证明，鸿蒙PC平台完全支持高性能Rust应用的移植和运行。以bat命令为例，我们不仅成功完成了交叉编译，还在真机上验证了其功能的完整性------语法高亮、行号显示等特性均正常工作。这充分说明了Rust生态与鸿蒙PC平台的良好兼容性。对于开发者而言，掌握这套交叉编译方法后，就可以将更多优秀的Rust CLI工具（如ripgrep、fd、exa等）快速适配到鸿蒙PC平台，丰富其应用生态。

值得注意的是，由于鸿蒙PC生态仍在快速发展中，SDK版本和工具链会持续更新。建议开发者在实际项目中根据具体需求选择合适的SDK版本，并关注官方文档的最新变化。同时，本文提供的故障排查方法和配置模板具有通用性，可作为后续开发过程中的参考基准。随着鸿蒙PC生态的成熟，相信会有更多简化的开发工具和标准化流程出现，进一步降低应用移植的门槛。

欢迎加入开源鸿蒙PC社区：https://harmonypc.csdn.net/ ，参与生态建设与技术交流。

【鸿蒙PC命令行适配】rust应用交叉编译环境搭建和bat命令的移植实战指南

一、前言

二、前置知识与环境要求

2.1 核心概念

2.2 环境要求

三、环境搭建步骤

3.1 安装Ubuntu 24.04

3.2 安装基础依赖

3.3 配置Rust基础环境

3.3.1 安装rustup

3.3.2 添加鸿蒙PC目标架构

3.4 下载并配置鸿蒙SDK

3.4.1 创建工作目录

3.4.2 下载鸿蒙SDK

3.4.3 解压SDK内置工具链

3.4.4 配置SDK环境变量

3.4.5 验证SDK配置成功

3.5 配置Rust交叉编译规则

3.6 rust交叉编译环境验证

3.6.1 创建测试项目

3.6.2 交叉编译项目

四、bat命令的构建和验证

4.1 源码下载

4.2 构建鸿蒙PC版本

4.3 鸿蒙pc真机测试

4.3.1 命令传输+自签名

4.3.2 命令测试1：查看python文件

五、常见问题与解决方案

5.1 编译时提示 "linker not found"

5.2 编译时提示：error[E0463]: can't find crate for std

5.3 下载安装Rust速度慢

六、总结

5.2 编译时提示：error[E0463]: can't find crate for `std`