在鸿蒙PC上适配rust_compiler手记
开源鸿蒙 PC 社区引导(先看这里)
- 加入开源鸿蒙 PC 社区: https://harmonypc.csdn.net/
- 本项目仓库: https://atomgit.com/next-lyle/ohos_rust_compiler
- 申请新建项目(社区 OpenHarmonyPCDeveloper 组织): https://atomgit.com/OpenHarmonyPCDeveloper
本教程记录 Rust 编译器工具链(rustc / cargo / rustfmt / clippy / rust-analyzer)在 OpenHarmony / HarmonyOS PC 上从零到跑通的完整适配过程。适配没有搬运任何二进制或重写编译器,而是直接使用 Rust 官方发布的 aarch64-unknown-linux-ohos(Tier 2 with Host Tools)原生 dist,在鸿蒙 PC 本机完成「下载 → 解压安装 → 内核签名 → 配置链接 → 全链路验证」。
全部分析、下载、安装、签名、验证均在鸿蒙 PC 本机完成(HongMeng Kernel 1.13.0,HarmonyOS 7.0 / API 26,MateBook Pro 形态),配合 DevBox 安装的 hnp 命令行包(binary-sign-tool 签名、xz 解压、clang 15 工具链),不需要额外的桌面开发机。
最终效果——签名后的工具链在本机 HiShell 中安装并正常运行(HiShell 内执行 rustc -vV && cargo --version,可以看到 host 为 aarch64-unknown-linux-ohos):

本教程按实际操作顺序分步说明:每一步做什么、遇到什么报错、怎么定位、怎么解决。所有命令与报错均真实执行与留档,完整报错索引见仓库内 doc/02-适配流程记录.md(E-001~E-013),环境要求明细见 doc/01-环境要求.md。
第一步:准备环境
1.1 安装 DevBox 并就位命令行工具
DevBox 应用安装后会在 /data/service/hnp/bin 提供一批 hnp 包(hnp 包自带 .codesign 签名,可直接执行),本适配用到其中三个:binary-sign-tool 负责 ELF 内核签名(sign -selfSign 1 自签模式),xz / unxz 5.8.2 负责解压官方 dist 的 .tar.xz,clang 15.0.4(即 aarch64-unknown-linux-ohos-clang)作为原生 C 编译器 / 目标链接器(已内置 ohos target)。
注意系统自带的 toybox tar 支持 -J 但需要外部 xz 后端,没装 DevBox 前无法解压 dist(E-001 系列坑的根源之一)。
1.2 必须知道的系统约束(每一条都实测过)
- 内核强制 ELF
.codesign签名:任何新放进来的 ELF,权限位正确、文件有效也照样Permission denied(126),必须用binary-sign-tool补签(E-009 用真实静态 busybox 实测确认); /tmp域特殊:在/tmp下运行的已签名二进制仍被拒,可执行内容一律放用户目录(/storage/Users/currentUser);- shell 脚本不需要签名(解释器
/bin/sh已签),只有 ELF 需要; - 本机
/tmp可写、/etc/passwd存在,与部分 HiShell 老镜像的「/tmp 只读、无 passwd」假设不同,脚本已做兼容。
第二步:下载官方 dist
官方 dist 在 https://static.rust-lang.org/dist/<日期>/,aarch64-unknown-linux-ohos host 的可用组件:rustc、rust-std、cargo、rustfmt、clippy、rust-analyzer(llvm-tools-preview 未发布,rust-lld 随 rustc 组件分发)。
用仓库自带的下载脚本(本步需要网络,在鸿蒙 PC 本机直接执行即可):
cd ohos_rust_compiler
DATE=2026-11-09 sh ohos-pc-adapt/scripts/fetch-dist.sh # 产物在 ./ohos-dist
实测注意(E-011):本机网络会间歇性 DNS 失败(Could not resolve host)导致整批失败。恢复后用断点续传逐个补齐,不必从头重来:
curl -fL -C - --retry 8 --retry-delay 5 -o <组件>.tar.xz.part \
https://static.rust-lang.org/dist/<日期>/<组件>-nightly-aarch64-unknown-linux-ohos.tar.xz
第三步:解压与安装
cd ohos-dist
export PATH=/data/service/hnp/bin:$PATH
for f in *.tar.xz; do tar -xJf "$f"; done
sh ../ohos-pc-adapt/scripts/install.sh --dist . --prefix $HOME/rust
# prefix: /storage/Users/currentUser/rust
# installed files: 174
install.sh 会把六个组件合并成统一前缀(bin/、lib/rustlib/aarch64-unknown-linux-ohos/...),并在缺 rustc 时硬失败、缺 rust-std 时告警。
第四步:签名(核心步骤)
安装后所有 ELF 都没有签名,直接运行必被拒。用 DevBox 的签名工具一次性给前缀内全部 ELF 自签:
sh ohos-pc-adapt/scripts/sign.sh --prefix $HOME/rust
# signed: 34 failed: 0
验证签名已生效:
binary-sign-tool display-sign -inFile $HOME/rust/bin/rustc
# → code signature is self-sign
之后每一个新编译/新链接的产物(可执行文件、proc-macro .so)都需要同样的签名才能运行,公式是:
binary-sign-tool sign -selfSign 1 -inFile <产物> -outFile <产物>
第五步:配置环境与 cargo
5.1 环境变量
. ohos-pc-adapt/scripts/env.sh
脚本自动处理:PATH 加入 $HOME/rust/bin、TMPDIR/CARGO_HOME 落到可写目录、恢复打包传输过程中丢失的 ELF 可执行位、HOME 回退(HiShell 导出无效 /root 的场景)。
5.2 cargo 的 libssl 缺口(E-012,垫片方案)
官方 cargo 动态链接了 OpenSSL 3.2+(缺 SSL_get0_group_name 符号),而 DevBox bind 包自带的 libssl.so.3 是 3.0 系,直接补库报 symbol not found。解决:符号垫片——用系统 clang 编一个薄 libssl.so,内部链接真实库并补上缺失符号(该符号只用于 TLS 分组日志,空实现返回 NULL 安全):
/* ssl_shim.c:补 3.2-only 符号,其余符号经 NEEDED 从真实库解析 */
const char *SSL_get0_group_name(const void *ssl) { (void)ssl; return (const char *)0; }
cd $HOME/rust/lib
cp /data/service/hnp/bind.org/bind_9.18.21/lib/libssl.so.3 . # 真实库
clang -target aarch64-linux-ohos -D__MUSL__ -shared -fPIC /tmp/ssl_shim.c \
-o libssl.so -L$HOME/rust/lib -l:libssl.so.3 -Wl,--no-as-needed
cp /data/service/hnp/bind.org/bind_9.18.21/lib/libcrypto.so.3 .
binary-sign-tool sign -selfSign 1 -inFile libssl.so -outFile libssl.so
binary-sign-tool sign -selfSign 1 -inFile libssl.so.3 -outFile libssl.so.3
binary-sign-tool sign -selfSign 1 -inFile libcrypto.so.3 -outFile libcrypto.so.3
注意 -l: 链接记录的是真实库的 SONAME(libssl.so.3),该文件必须留在同目录,否则运行时悬空(实测踩到)。
5.3 cargo linker(E-013)
设备上没有 cc,cargo 默认链接器必须显式配置为 DevBox 的目标 clang:
# ~/.cargo/config.toml
[target.aarch64-unknown-linux-ohos]
linker = "/data/service/hnp/bin/aarch64-unknown-linux-ohos-clang"
第六步:验证
sh ohos-pc-adapt/scripts/doctor.sh --prefix $HOME/rust
# OK=25 WARN=11 FAIL=0(WARN:rustdoc 缺失、可选运行库等已知项)
sh ohos-pc-adapt/scripts/smoke.sh --prefix $HOME/rust
# PASS=5 FAIL=0 SKIP=7
两条全链路实测:
# rustc 全链路:编译 → 链接 → 签名 → 运行
printf 'fn main(){println!("hello from rust on harmonyos pc");}' > hello.rs
rustc hello.rs -C linker=/data/service/hnp/bin/aarch64-unknown-linux-ohos-clang -o hello
binary-sign-tool sign -selfSign 1 -inFile hello -outFile hello
./hello
# hello from rust on harmonyos pc
# cargo 全链路
cargo new hello --bin && cd hello && cargo build
binary-sign-tool sign -selfSign 1 -inFile target/debug/hello -outFile target/debug/hello
./target/debug/hello
# Hello, world!
约束与限制(已知缺口)
rustdoc 未适配:官方 OHOS dist 的 rustc 组件内无 rustdoc(D3:Dockerfile 工具名 rustdocs 拼写,本仓库已修复源码),cargo doc 暂不可用,待 dist 重建。
设备端 C 编译能用但受限:DevBox 的 hnp clang 15 target 即 ohos,可以直接编译 C;但 -sys crate 需要完整 sysroot 的场景仍受限。
$ clang -target aarch64-linux-ohos --version
# OpenHarmony clang version 15.0.4
sanitizer 不可用:设备 39-bit VA,运行时未随 OHOS bootstrap 构建。miri 不可用:官方不支持 OHOS 目标。
HAP 内运行工具链不可行:HAP 沙箱不能 exec 任意 CLI,工具链只能走 HiShell/终端。
超大工程 TLS 待观察:emutls + pthread key 上限,大量 proc-macro 的场景需 probe-runtime.sh 实测。
遇到的报错与排查思路
整个适配过程中没有一步是顺利的,把高频的几个坑在这里按排查思路串一遍,完整记录见 doc/02-适配流程记录.md(E-001~E-013)。
最早出现也最难排查的是签名问题:安装完成后直接运行 rustc 会得到 Permission denied(退出码 126),第一反应往往是权限位或文件损坏,但实测 chmod +x 有效、ELF 头完好仍然被拒,换到其他目录执行结果不变——最后用「一个确定有效的静态 ELF 也被拒、系统自带的二进制都能跑」这组对照实验锁定了内核 .codesign 强制校验(E-009),解法是 binary-sign-tool sign -selfSign 1 补签,并且此后每个新编译产物都要签。
第二类是工具链缺口:toybox tar 虽然支持 -J 参数,实际解压时却报 exec xz: No such file or directory(它依赖外部 xz 后端),DevBox 安装后由 hnp 包提供 xz 5.8.2 才解决。cargo 的问题更隐蔽——先是 Error loading shared library libssl.so,补上 bind 包的库后又变成 SSL_get0_group_name: symbol not found:官方 cargo 链接的是 OpenSSL 3.2+,而 bind 的库是 3.0 系。这里选择编译一个符号垫片而不是换库(第五步 5.2),因为缺失的符号只有一个、且只用于 TLS 日志输出。紧接着 linker 'cc' not found 提醒我们设备上没有 C 编译器,把 cargo 的 linker 配置成 hnp 的目标 clang 即可。
还有两类环境性问题值得记住:一是本机网络会间歇性 DNS 失败打断 dist 下载(E-011),恢复后用 curl -C - 断点续传不必从头重来;二是执行域差异——/tmp 下即使签名过的二进制也会被拒(Operation not permitted),可执行内容必须放在用户目录,而 shell 脚本因为解释器已签所以无需签名。
功能到底能用到什么程度
按 T0 / T1 / T2 三档说明迁移能力,状态分「能用 / 待验证 / 未适配」,结论均来自本机实测证据。
T0 基础能力
这一档是底线:装得上、签得了、跑得动。官方 dist 下载与安装已在第二步、第三步完成——6 组件 174 文件合并到 $HOME/rust;内核签名工具链在第四步打通——34 个 ELF 全部自签成功,display-sign 确认生效:
$ binary-sign-tool display-sign -inFile $HOME/rust/bin/rustc
# → code signature is self-sign
rustc 与 cargo 的全链路(编译 → 链接 → 签名 → 运行)在第六步实测通过:
$ rustc -vV
host: aarch64-unknown-linux-ohos
$ ./hello
hello from rust on harmonyos pc
$ ./target/debug/hello
Hello, world!
rustfmt / clippy 的 --version 与实际格式化/检查均正常;doctor / smoke 自检 doctor.sh FAIL=0、smoke.sh PASS=5 FAIL=0。
T1 主要能力(日常开发核心)
纯 Rust 工程的开发流程(build/run)即第六步 cargo 全链路,真机可用;proc-macro 的编译与加载由 smoke.sh 覆盖,签名链路已打通。
明确缺口是 rustdoc:官方 dist 缺 rustdoc(D3),cargo doc 待 dist 重建。-sys crate / build.rs 的 C 代码标记为待验证——DevBox clang 可用(见「约束与限制」),但完整 sysroot 场景未实测。
T2 增强能力
sanitizer(39-bit VA + 运行时未构建)、miri(上游不支持 OHOS 目标)、HAP 形态分发(沙箱限制,工具链只走 HiShell)均为未适配,原因见「约束与限制」一节。
一句话总结:本项目已在鸿蒙 PC 本机完成「下载 → 安装 → 签名 → 配置 → 验证」全链路,rustc/cargo/rustfmt/clippy 真机可用;rustdoc 是唯一明确缺口,等上游 dist 重建生效。
改动了哪些代码、为什么
本次适配没有改动 Rust 编译器本身的任何源码,全部交付物是仓库里新增的适配脚本集 ohos-pc-adapt/scripts/。每个脚本对应上面流程中的一步,改动原因都来自鸿蒙 PC 与常规 Linux 的差异。逐个说明关键实现:
install.sh——为什么不跑官方 install.sh。官方 dist 每个组件自带安装脚本,但那些是 bash 脚本,而鸿蒙 PC 的系统 shell 不保证有 bash。所以 install.sh 改为直接合并各组件的载荷目录(bin / lib / libexec / share / etc)到统一前缀,并限制查找深度,避免把 lib/rustlib/<triple>/lib 这类深层目录误认为载荷目录:
# 深度受限的载荷目录收集:mindepth 2 / maxdepth 4,排除 lib、share 内部
PAYLOAD_DIRS=$(find "$DIST" -mindepth 2 -maxdepth 4 -type d \
\( -name bin -o -name lib -o -name libexec -o -name share -o -name etc \) \
! -path '*/lib/*' ! -path '*/share/*' | sort)
合并后兜底恢复可执行位(打包传输会丢权限位),并在缺 rustc 时硬失败、缺 cargo / rust-std 时告警——前者是硬性前提,后者只是功能缺失,所以要区分严重级别。
sign.sh——为什么要自己识别 ELF。内核在 execve 时校验 ELF 的 .codesign 节:未签名报 EACCES、哈希不匹配报 EPERM,chmod 无关。但签名只需覆盖 ELF,shell 脚本因为解释器已签而无需处理,所以脚本逐文件读前四字节魔数判断:
is_elf() {
# 0x7f 'E' 'L' 'F'
magic=$(head -c 4 "$1" 2>/dev/null | od -An -tx1 2>/dev/null | tr -d ' \n')
[ "$magic" = "7f454c46" ]
}
签名工具参数在不同 SDK 版本间有差异,因此用 SIGN_TOOL / SIGN_ARGS / SIGN_CMD 三层环境变量留了覆盖口子,--check 模式只列出 ELF 不签名,便于先核对清单再动手。
env.sh——三个环境坑集中处理。HiShell 会导出一个无效的 HOME=/root(该目录在终端命名空间不存在),而 CARGO_HOME、TMPDIR 都依赖 HOME,所以先探测可写性再回退到当前目录;/tmp 域特殊(已签名的二进制放进去照样被拒),TMPDIR 必须落到用户目录;HMDFS 不支持硬链接,cargo 的硬链接缓存自动退化为拷贝,无需额外配置:
if [ -z "${HOME:-}" ] || [ ! -d "${HOME:-/nonexistent}" ] || [ ! -w "${HOME:-/nonexistent}" ]; then
HOME=${PWD:-/storage/Users/currentUser}
export HOME
fi
ohos-clang-wrapper.sh + link-sign-wrapper.sh——链接与签名合并成一步。设备上没有 cc,rustc 的每个链接产物都会立刻被内核拒绝,逐个补签很容易漏(proc-macro 的 .so 是编译中途生成的)。这两个包装器把「以 ohos target 链接」和「链接后自动自签」封装在一起,cargo 侧则通过 ~/.cargo/config.toml 把 linker 指向包装器:
[target.aarch64-unknown-linux-ohos]
linker = "/data/service/hnp/bin/aarch64-unknown-linux-ohos-clang"
ssl_shim.c——为什么编符号垫片而不是换库。官方 cargo 动态链接 OpenSSL 3.2+,DevBox 的 libssl.so.3 是 3.0 系,缺的符号只有 SSL_get0_group_name 一个、且只用于 TLS 分组日志。为这一个符号换库或重编 OpenSSL 得不偿失,垫片是影响面最小的方案(详见第五步 5.2)。
doctor.sh / smoke.sh / probe-runtime.sh——把「能不能用」变成可复核的结论。doctor.sh 对安装结果做 25+ 项逐项体检(FAIL=0 才算过),smoke.sh 覆盖编译、链接、签名、运行、proc-macro 加载五条主链路,probe-runtime.sh 针对超大工程 TLS(emutls + pthread key 上限)做压力探测。适配早期的结论靠手工点验,不可复现,脚本化之后每次改动都能重放同一组证据。
报错记录与回滚
- 报错与解决方案的完整索引:
doc/02-适配流程记录.md; - 环境要求与检查清单:
doc/01-环境要求.md; - 回滚:
rm -rf $HOME/rust $HOME/.cargo/config.toml
更多推荐



所有评论(0)