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

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 IDErustup工具链之间的“窄沟”,仅有两步操作需被执行:

  1. 搭建面向ohos的交叉编译环境。

  • 限于作者dev boxWindows 11,所以本篇文章仅分享从Windowsohos的交叉编译环境搭建心得。

将交叉编译输出的.so文件注入DevEco Studio工作流。

搭建Windows  ➞ ohos交叉编译环境

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

  • 面向64ARM CPUaarch64-unknown-linux-ohos方案。

  • 面向32ARM CPUarmv7-unknown-linux-ohos方案。

  • 面向64AMD / Intel CPUx86_64-unknown-linux-ohos方案。

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

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

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

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

【厂商】栏的unkownMozilla公司的“锅”,而不是我定的。就我本意,这一栏馁馁的是汉语拼音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. 若出现的是【欢迎界面】,就从菜单ConfigureSettings,打开Settings对话框

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

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

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

  6. 勾选native复选框

  7. 点击OK按钮

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

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

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

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

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

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

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

技术方案选型

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

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

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


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

采用【方案二】的准备工作与先决条件
  1. rustup工具链,补装【标准库】源码(即,rust-src组件)。

    从命令行,立即执行且仅执行一次:

    rustup ***ponent 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】面向64ARM 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】面向32ARM 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】面向64AMD / 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.***piler_builtins]
opt-level = 2

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

  1. 配置项linker相对路径引用链接器文件的背后逻辑是cargo总是以config.toml父文件夹(.cargo)所处目录为起点开始解析相对路径(,而不是以config.toml的同级目录为起点)。所以,本例中的./路径前缀对应的就是登录账号的根目录%UserProfile%

  2. 配置项opt-level,借助【Profile重写(i.e. Override)】配置表头[profile.dev.package.***piler_builtins],仅将【开发编译】模式下【标准库】内***piler_builtins crate的代码优化级别强制锚定于2。否则,cargo build -Zbuild-std --target=aarch64-unknown-linux-ohos指令(注意:没有--release参数)会概率性地失败于exit code: 0xc0000005, STATUS_A***ESS_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. 将【标准库】源码作为普通依赖cratecrate业务程序一起编译

  3. 并行启动三个JOB进程对同一套Rust源码同时执行三组交叉编译操作

  4. 交叉编译输出三个文件名相同ABI格式不同的动态链接库.so文件

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

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

git clone git@github.***: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 = ["dylib"]

[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

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

最后,在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) PackageDevEco 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的引用路径。否则,会编译失败!

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

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

  1. build.rs作为【前置处理】程序

    1. 从环境变量,收集.so文件的位置信息

    2. 生成[CMD] COPY /Y[Shell] cp -f文件复制指令

    3. 将【文件复制】指令尾追加至同一个.cmd / .sh脚本文件

  2. post_build.rs作为【后置处理】程序

    1. 执行被写入【文件复制】指令的程序文件,并

    2. 删除该程序文件

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

还是看图吧,一图抵千词

设计很完美但现实很骨感,因为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"
    }

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


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

于是,鸿蒙应用软件开发程序员就能在etsts代码编辑器内获得针对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.***:stuartZhang/Arkts-NAPI-Rust-Demo.git

  2. VSCode内,

    1. 打开entry/src/main/rust目录

    2. 敲击Alt + T + R键。

    3. 依次点击菜单项buildohos-build--release

    4. 观察控制台输出日志,等待交叉编译结束。

  3. DevEco Studio IDE内,

    image
    1. 打开工程根目录

    2. 启动手机模拟器

    3. 敲击Shift + F10键,运行移动端程序

结束语与扩展阅读

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

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

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


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


转载请说明出处内容投诉
CSS教程_站长资源网 » 【社区投稿】Rust登陆华为鸿蒙操作系统之Native模块开发

发表评论

欢迎 访客 发表评论

一个令你着迷的主题!

查看演示 官网购买