< 返回我的博客

Rust登陆【华为鸿蒙】操作系统之Native模块开发

爱国的张浩予 发表于 2024-02-16 17:28

Tags：鸿蒙,arkts,n-api,nodejs,DevEco_Studio,vscode,交叉编译,ohos,ohsdk

Rust登陆【华为鸿蒙】操作系统之Native模块开发

名词解释

  • 【鸿蒙操作系统】的英文全名是Open Harmony Operation System。正文将以其首字母缩写词ohos引用该词条。
  • 【鸿蒙软件开发工具包】的英文全名是Open Harmony Software Development Kit。正文也将以它的首字母缩写词ohsdk引用该词条。
  • DevEco Studio IDE是【华为】为鸿蒙应用程序开发免费提供的集成开发环境。它的最新稳定版内置了ohsdk 3.1.0 (API v9)。
  • 【Native模块】是指由遵循了ArkTs NAPI接口规范的C/Cpp/Rust程序经交叉编译输出的链接库.so文件。

前言

到写文章时止，虽然华为技术团队既未将rustup工具链无缝集成入DevEco Studio IDE也未提供ArkTs + Rust的“一站式”混合编程体验，但Rust登陆ohos依旧势不可挡，因为相较于Rust带来的生产效率收益（参照c / cpp），搭建交叉编译环境的人工成本真的微不足道。甚至，求助于【操作系统镜像】或Docker技术，@Rustacean 还能避免这类重复性劳动的再次发生。

为了填补DevEco Studio IDE与rustup工具链之间的“窄沟”，仅有两步操作需被执行：

  1. 搭建面向ohos的交叉编译环境。
    • 限于作者dev box是Windows 11，所以本篇文章仅分享从Windows至ohos的交叉编译环境搭建心得。
  2. 将交叉编译输出的.so文件注入DevEco Studio工作流。

搭建Windows ➞ ohos交叉编译环境

鉴于华为硬件产品的三款主流CPU架构，@Rustacean 需同时准备三套交叉编译方案，分别是：

  • 面向64位ARM CPU的aarch64-unknown-linux-ohos方案。
  • 面向32位ARM CPU的armv7-unknown-linux-ohos方案。
  • 面向64位AMD / Intel CPU的x86_64-unknown-linux-ohos方案。

前两套方案是为【真机】设备提供动态链接库/Native模块；而后一套方案则是服务于手机模拟器（虚拟机）的。

image

上表中Triple的信息描述格式统一是：

<CPU架构><CPU子架构>-<厂商>-<操作系统>-<应用程序二进制接口格式>

于是，armv7-unknown-linux-ohos应被读作

image

【厂商】栏的unkown是Mozilla公司的“锅”，而不是我定的。就我本意，这一栏馁馁的是汉语拼音HuaWei。

下面上干货了...

第一步，给ohsdk补装native组件

DevEco Studio IDE的内置ohsdk位于%LocalAppData%\Huawei\Sdk\openharmony\<API 版本号>目录下，但其初始安装却缺失了native组件（— 可能是因为这个模块太大了，超过2GB）。所以，@Rustacean 需要

  1. 补装native组件
  2. 记住ohsdk对应的【API版本号】，因为后续配置得用。

具体步骤

  1. 打开DevEco Studio IDE

  2. 若出现的是【欢迎界面】，就从菜单Configure ➞ Settings，打开Settings对话框

  3. 若出现的是【工程界面】，就从菜单File ➞ Settings，打开Settings对话框

  4. 从对话框左侧选择SDK；从右侧查看Platform选项卡下面的内容

  5. 寻找并记忆被勾选的【SDK版本号 (API版本号)】。比如，下图中的3.1.0 (API 9)。

    image

  6. 勾选native复选框

  7. 点击OK按钮

  8. 等待native组件安装完成 — 耐心点儿，等待时间可不短

待上述操作都正常完成之后，便可见如下所示的新目录结构

image

第二步，重新编译Rust标准库

之所以把事情搞这么大是因为Mozilla厂方并没有为ohos提供预编译的【标准库】二进制文件。于是，尽管ohos已被纳入了rustc交叉编译支持清单（请见下图）

image

，但直接执行交叉编译指令

cargo build --release --target=aarch64-unknown-linux-ohos

还是会遭遇失败和看到E0463号错误

image

技术方案选型

编译【标准库】源码有两条技术路径

  1. 重新编译整条rustup工具链，捎带着也就编译出【标准库】了 — 难！我没搞定

  2. 将【标准库】作为普通依赖crate和Cargo (Lib) Package工程的业务代码一起编译（— 注：这个解释并不精确，因为细究起来主crate与依赖crates是搅和在一起的各自独立编译，而不是绝对意义上的“一锅烩”）。下图中被红框圈定的crates就都出自于【标准库】

    image

我选择了第二条技术路线。虽然后一条技术路线拖长了程序编译的总用时，但它仅会影响首次编译操作。从那以后，借助sccache编译缓存技术，由【标准库】引入的额外延时几乎可以忽略不计。更重要的是，该技术路线不会阻塞 @Rustacean 对rustup工具链的后续升级。咱们随时都可以rustup update。

采用【方案二】的准备工作与先决条件

  1. 给rustup工具链，补装【标准库】源码（即，rust-src组件）。

    从命令行，立即执行且仅执行一次：

    rustup component add rust-src

  2. 启用nigtly工具链，因为工具链的stable版本还尚不支持“裹挟【标准库】共同编译”的新功能。

    从命令行，立即执行且仅执行一次：

    rustup default nightly

  3. 采用ohsdk内置的llvm - clang作为rustc链接器（下一节将详细介绍）

  4. 向交叉编译指令添加新命令行参数-Zbuild-std。

    1. cargo会透传该参数给rustc并指示编译器不是寻找现成的【标准库】链接文件而是现场编译【标准库】源码。

    2. 编译指令也将变为

      cargo +nightly build -Zbuild-std --release --target=aarch64-unknown-linux-ohos

如何把ohsdk内置的llvm - clang作为rustc链接器

第一步，回忆之前记下的【鸿蒙API版本号】数字和新建环境变量OHOS_API_V。【推荐】从Cargo全局配置文件%UserProfile%\.cargo\config.toml新建OHOS_API_V环境变量，因为

  • 一方面，这可最小化对系统环境的“污染” — 该变量仅对Rust交叉编译有用，没有必要系统级全局可见。
  • 另一方面，它随时可被【会话级】同名环境变量短暂复写，方便以后临时变更做试验。

打开%UserProfile%\.cargo\config.toml配置文件和添加配置表

[env]
OHOS_API_V = "9"

【注意】伴随今后ohsdk的自动升级，该环境变量的值须被同步地手动更新，以避免编译失败。

第二步，将ohsdk目录下的LLVM前端编译器llvm\bin\clang.exe包装为rustc的【鸿蒙链接器】。敲黑板，重点来了！@Rustacean 需分别构建三个链接器，以服务三套交叉编译方案，和向华为的三类硬件设备提供.so文件。于是，有

  • 【链接器1】面向64位ARM CPU真机的aarch64-unknown-linux-ohos交叉编译方案。在%UserProfile%目录下，新建cmd文件aarch64-unknown-linux-ohos-clang.cmd，并添加如下代码

    %LocalAppData%\Huawei\Sdk\openharmony\%OHOS_API_V%\native\llvm\bin\clang.exe ^
-target aarch64-linux-ohos ^
--sysroot=%LocalAppData%\Huawei\Sdk\openharmony\%OHOS_API_V%\native\sysroot ^
-D__MUSL__ %*

  • 【链接器2】面向32位ARM CPU真机的armv7-unknown-linux-ohos交叉编译方案。在%UserProfile%目录下，新建cmd文件armv7-unknown-linux-ohos-clang.cmd，并添加如下代码

    %LocalAppData%\Huawei\Sdk\openharmony\%OHOS_API_V%\native\llvm\bin\clang.exe ^
-target arm-linux-ohos ^
--sysroot=%LocalAppData%\Huawei\Sdk\openharmony\%OHOS_API_V%\native\sysroot ^
-D__MUSL__ ^
-march=armv7-a ^
-mfloat-abi=softfp ^
-mtune=generic-armv7-a ^
-mthumb %*

  • 【链接器3】面向64位AMD / Intel CPU模拟器的x86_64-unknown-linux-ohos交叉编译方案。在%UserProfile%目录下，新建cmd文件x86_64-unknown-linux-ohos-clang.cmd，并添加如下代码

    %LocalAppData%\Huawei\Sdk\openharmony\%OHOS_API_V%\native\llvm\bin\clang.exe ^
-target x86_64-linux-ohos ^
--sysroot=%LocalAppData%\Huawei\Sdk\openharmony\%OHOS_API_V%\native\sysroot ^
-D__MUSL__ %*

第三步，全局且有条件地向rustc装配【鸿蒙链接器】。其中，

  • 【全局】意味着修改Cargo全局配置文件%UserProfile%\.cargo\config.toml和作用于所有Cargo Package工程。
  • 【有条件】意味着采用条件编译语法target.<triple>.linker限定该【链接器】仅生效于面向ohos的交叉编译操作。

具体作法，打开%UserProfile%\.cargo\config.toml配置文件和添加配置表

[target.aarch64-unknown-linux-ohos]
linker = "./aarch64-unknown-linux-ohos-clang.cmd"
[target.armv7-unknown-linux-ohos]
linker = "./armv7-unknown-linux-ohos-clang.cmd"
[target.x86_64-unknown-linux-ohos]
linker = "./x86_64-unknown-linux-ohos-clang.cmd"
[profile.dev.package.compiler_builtins]
opt-level = 2

再对前面配置片段补充两点解释：

  1. 配置项linker以相对路径引用链接器文件的背后逻辑是cargo总是以config.toml的父文件夹（.cargo）所处目录为起点开始解析相对路径（，而不是以config.toml的同级目录为起点）。所以，本例中的./路径前缀对应的就是登录账号的根目录%UserProfile%。
  2. 配置项opt-level，借助【Profile重写（i.e. Override）】配置表头[profile.dev.package.compiler_builtins]，仅将【开发编译】模式下【标准库】内compiler_builtins crate的代码优化级别强制锚定于2。否则，cargo build -Zbuild-std --target=aarch64-unknown-linux-ohos指令（注意：没有--release参数）会概率性地失败于exit code: 0xc0000005, STATUS_ACCESS_VIOLATION错误。

第四步，给冗长的交叉编译指令约定（短）别名。

还是打开%UserProfile%\.cargo\config.toml配置文件和增补如下配置表

[alias]
ohos-build = ["build", "-Zbuild-std", "--target=aarch64-unknown-linux-ohos", "--target=armv7-unknown-linux-ohos", "--target=x86_64-unknown-linux-ohos"]

于是，只要执行一条cargo ohos-build指令就相当于连续执行下面三条编译指令：

  1. cargo build -Zbuild-std --target=aarch64-unknown-linux-ohos
  2. cargo build -Zbuild-std --target=armv7-unknown-linux-ohos
  3. cargo build -Zbuild-std --target=x86_64-unknown-linux-ohos

总结交叉编译环境的搭建成果

以后每次在Cargo (Lib) Package工程根目录下执行

cargo ohos-build --release

，编译器都会立即

  1. 唤起ohsdk内置的LLVM前端编译器llvm - clang作为rustc链接器
  2. 将【标准库】源码作为普通依赖crate与主crate业务程序一起编译
  3. 并行启动三个JOB进程对同一套Rust源码同时执行三组交叉编译操作
  4. 交叉编译输出三个文件名相同但 ABI格式不同的动态链接库.so文件

新建Cargo (Library) Package工程，验证交叉编译环境

首先，克隆stuartZhang/socket2至本地，并将代码分支切至v0.4.x。

git clone git@github.com:stuartZhang/socket2.git
cd socket2
git checkout -q v0.4.x

关于这一步操作的必要性，我已经详细地阐述于ohos-node-bindgen还不能被直接使用章节了。简单地讲，这是为了绕过socket2 crate对华为鸿蒙操作系统的不兼容缺陷。

然后，从命令行，新建Cargo (Library) Package工程

cd ..
cargo new --lib calculator
code calculator

其次，在VSCode内，打开Cargo.toml文件，和追加如下内容

[lib]
crate-type = ["cdylib"]

[dependencies]
ohos-node-bindgen = "6.0.3"
socket2 = "0.4.10"

[patch.crates-io]
socket2 = { path = "../socket2" }

前面配置片段内的【依赖图重写】配置表[patch.crates-io]指示Cargo包管理器使用本地的stuartZhang/socket2 crate山寨货替换crates.io上的正品，因为正品不兼容华为操作系统。

接着，从VSCode打开src/lib.rs文件，和增补如下Demo代码。这是一段简单的整数加运算程序。请把注意力聚焦在【派生宏】的使用上。

use ::ohos_node_bindgen::derive::ohos_node_bindgen;
#[ohos_node_bindgen]
fn add(first: i32, second: i32) -> i32 {
    first + second
}

再次，执行交叉编译

cargo ohos-build --release

最后，从【资源管理器】查看编译输出结果

Cargo (Library) Package 工程根目录
├── Cargo.toml
├── src — Rust 源码目录
├── target
│  ├── aarch64-unknown-linux-ohos
│  │  └── release
│  │     └── libcalculator.so
│  ├── armv7-unknown-linux-ohos
│  │  └── release
│  │     └── libcalculator.so
│  ├── x86_64-unknown-linux-ohos
│  │  └── release
│  │     └── libcalculator.so

值得注意的是，编译输出的链接库文件名是有lib前缀的。所以，Native模块的文件名是lib<包名>.so，而不是<包名>.so。

将Native模块注入普通的DevEco Studio工程

Native模块就是由前面交叉编译输出的ArkTs N-API链接库.so文件。

首先，从DevEco Studio IDE新建/打开普通Empty Ability工程。

然后，修改模块级的build-profile.json5文件（比如，entry/build-profile.json5），和添加如下配置项至buildOption节点

"externalNativeOptions": {
  "abiFilters": [
    "arm64-v8a",
    "armeabi-v7a",
    "x86_64"
  ]
}

其次，在模块根目录下，创建下面三个子文件夹

  • libs/arm64-v8a
  • libs/armeabi-v7a
  • libs/x86_64

接着，依次向它们复制入编译好的链接库文件。例如，

image

最后，在ArkTs业务代码内（比如，entry/src/main/ets/pages/Index.ets），以ES Module语法，导入Native模块，和调用其成员方法

import calculator from 'libcalculator.so';
const result = calculator.add(2, 3);

总的来讲，调用端的ets代码就这么简单！但还是有三处优化可做以改善开发体验：

优化DevEco Studio工程目录结构

将Cargo (Lib) Package与DevEco Studio Project合并为一个工程更有利于提高Rust + ArkTs的混合编程生产力。所以，如下DevEco Studio工程目录结构是被强力推荐的：

DevEco Studio 工程根目录
├── entry — 模块根目录
│   ├── libs — 交叉编译输出的 .so 文件都被复制到下面的子文件夹内
│   │   ├── arm64-v8a
│   │   ├── armeabi-v7a
│   │   └── x86_64
│   ├── src
│   │   ├── main
│   │   │  ├── resources
│   │   │  ├── cpp  — *旧有*的 Cpp(ArkTs N-API) 工程目录
│   │   │  ├── ets  — *旧有*的 ArkTs 源码目录
│   │   │  ├── rust — *新建*的 Rust(ArkTs N-API) 工程目录
│   │   │  │   ├── Cargo.toml
│   │   │  │   ├── src — Rust 源码目录
│   │   │  │   ├── target
│   │   │  │   │  ├── aarch64-unknown-linux-ohos
│   │   │  │   │  │  └── release
│   │   │  │   │  ├── armv7-unknown-linux-ohos
│   │   │  │   │  │  └── release
│   │   │  │   │  ├── x86_64-unknown-linux-ohos
│   │   │  │   │  │  └── release

将Cargo (Lib) Package降级为DevEco Studio Project内某个特定模块下的子工程有两个好处：

  1. 同一个DevEco Studio工程内可同时包含多个Native子工程。
  2. 每个Native子工程既可独占一个模块以达成与主模块业务代码有限隔离的目的，也能与ets程序“混住”耦合于相同模块内。

友情提示

在移动Cargo (Lib) Package工程位置后，千万别忘了同步修改Cargo.toml配置文件中【依赖图重写】配置表[patch.crates-io]对本地stuartZhang/socket2 crate的引用路径。否则，会编译失败！

若假设stuartZhang/socket2 crate与DevEco Studio Project处理于平级目录，那么【依赖图重写】配置表应该改为

[patch.crates-io]
socket2 = { path = "../../../../../socket2" }

自动化链接库.so文件的复制操作

在每次执行cargo ohos-build --release指令之后都徒手复制三个.so文件至不同的文件夹是非常低效的，所以 @Rustacean 有必要给Cargo编写build.rs与post_build.rs构建程序，以扩展包管理器在编译前与编译后的处理行为，并自动完成文件复制操作。其中，

  1. build.rs作为【前置处理】程序
    1. 从环境变量，收集.so文件的位置信息
    2. 生成[CMD] COPY /Y或[Shell] cp -f文件复制指令
    3. 将【文件复制】指令尾追加至同一个.cmd / .sh脚本文件
  2. post_build.rs作为【后置处理】程序
    1. 执行被写入【文件复制】指令的程序文件，并
    2. 删除该程序文件

【打广告】build.rs与post_build.rs皆未对上下文做任何的假设。所以，它们可被零成本地复用于其它同类工程中。

还是看图吧，一图抵千词

image

设计很完美但现实很骨感，因为Mozilla厂方的rustup工具链尚不支持【后置处理】。所以，@Rustacean 需

  1. 额外安装功能增补包cargo-post

    cargo install cargo-post

  2. 修改Cargo全局配置文件%UserProfile%\.cargo\config.toml中的ohos-build别名设置，以使cargo-post生效

    [alias]
ohos-build = ["post", "build", "-Zbuild-std", "--target=aarch64-unknown-linux-ohos", "--target=armv7-unknown-linux-ohos", "--target=x86_64-unknown-linux-ohos"]

    【注意】在"build"左侧新添加了"post"数组项

给Native模块导出接口，添加.d.ts类型提示

DevEco Studio IDE并没有集成类似于DLL Export Viewer的【动态链接库外部接口反射工具】。所以需要

  1. @Rustacean 在输出.so文件的同时也提供一份接口类型说明的.d.ts文件（— 其功能几乎等效于C头文件），并
  2. 将该类型说明文件注入DevEco Studio工作流

接下来，我沿着前面Rust + ArkTs混合编程的新目录结构，描述操作步骤：

  1. 在模块entry的根目录下，创建src/main/rust/types/libcalculator子目录。注意：路径末端的文件夹名libcalculator是链接库文件的basename。

  2. 在新建文件夹内，再新建文件index.d.ts和添入Native模块导出函数的函数签名

    export const add: (frist: number, second: number) => number;

  3. 接着新建文件oh-package.json5和添入Native模块的摘要信息。

    {
    "name": "libcalculator.so",
    "types": "./index.d.ts",
    "version": "0.1.0",
    "description": "ArkTs NAPI 原生模块示例"
}

    其中，

    1. name字段就是链接库的文件名（含扩展名）。
    2. types字段是指向类型说明文件的相对路径。
    3. version字段是Native模块版本号。【推荐】该字段值与Cargo (Lib) Package子工程中Cargo.toml配置文件内[package]配置表下version配置项的值保持一致 — 这又是一处纯人工同步点。
    4. description字段是Native模块描述信息。

  4. 打开entry模块的oh-package.json5文件，并添加对Native模块的依赖项条目。

    "dependencies": {
    "libcalculator.so": "file:src/main/rust/types/libcalculator"
}

    在依赖项条目中，左侧是链接库的文件名；而右侧是指向了类型说明文件所处文件夹的相对目录。

    image

  5. 最后，从DevEco Studio IDE依次点击菜单项Build ➞ Rebuild Project重新构建整个工程和使配置项修改生效。

于是，鸿蒙应用软件开发程序员就能在ets与ts代码编辑器内获得针对Native模块API的丰富类型提示了。

线上例程

我已将上述全部文字描述内容都例程化到github工程Arkts-NAPI-Rust-Demo内了。线下运行该工程可加强对文章繁杂内容的理解。

运行例程工程的环境要求

  1. rustc 1.75.0-nightly
  2. VSCode 1.86
  3. ohsdk 3.1.0(API v9)
  4. DevEco Studio 3.1.1 Release

运行例程工程的具体步骤

  1. 克隆git@github.com:stuartZhang/Arkts-NAPI-Rust-Demo.git

  2. 在VSCode内，

    1. 打开entry/src/main/rust目录
    2. 敲击Alt + T + R键。
    3. 从Command Palette下拉列表，依次点击build ➞ ohos-build ➞ --release
    4. 观察控制台输出日志，等待交叉编译结束。

  3. 在DevEco Studio IDE内，

    1. 打开工程根目录
    2. 启动手机模拟器
    3. 敲击Shift + F10键，运行移动端程序

    image

结束语与扩展阅读

搞定【交叉编译】难关仅只是鸿蒙Rust原生开发万里征程的第一步。加深对ArkTs - NAPI接口定义的理解才是【形成生产力】的核心任务。好消息是

  1. ArkTs - NAPI与nodejs N-API高度相似。至少截至目前，它们的相似度还>= 95%。所以，已熟悉nodejs原生模块编程的“老司机”们上手鸿蒙ArkTs - NAPI应该不难。

  2. 另外，我在春节假期期间贡献的ohos-node-bindgen crate更可大幅降低ArkTs - NAPI原生开发的复杂度。请对比下图左右侧的代码量

    image

    所以，ohos-node-bindgen crate值得大家点star呀！也请大家给Arkts-NAPI-Rust-Demo点star！

ohos-node-bindgen摘要

评论区

写评论
ManonLoki 2024-02-17 21:57

浩予的文章 是越来越追不上了……

1 共 1 条评论, 1 页