# ohos_napi_rs

**Repository Path**: openharmony-tpc/ohos_napi_rs

## Basic Information

- **Project Name**: ohos_napi_rs
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2024-08-23
- **Last Updated**: 2025-04-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 🚨 **重要提示 | IMPORTANT**
>
> **⚠️ 此代码仓已归档。新地址请访问 [ohos_napi_rs](https://gitcode.com/openharmony-tpc/ohos_napi_rs)。| ⚠️ This repository has been archived. For the new address, please visit [ohos_napi_rs](https://gitcode.com/openharmony-tpc/ohos_napi_rs).**
>
---
>
## OHOS_NAPI_RS

## 简介
ohos_napi_rs(forked from napi-rs)是一个用于实现ArkTS和Rust通信的框架。为用户提供了ArkTS和Rust相互调用的能力。

**图 1**  ohos_napi_rs在 OpenHarmony 中的位置

![structure](./figures/structure.png)

一般情况下OpenHarmony应用开发使用ArkTS/JS语言，但部分场景由于性能、效率等要求，比如游戏、物理模拟等，需要依赖使用现有的C/C++库。

ohos_napi_rs为开发者提供ArkTS和Rust模块之间的交互能力。包括ArkTS和Rust数据类型转换、函数相互调用的能力。

- `ArkTS`：OpenHarmony应用开发语言；
- `ArkTS Native Module(Rust)`：使用Rust开发的native模块；
- `ArkTS Native Module(C++)`：使用C++开发的native模块；
- `ohos_napi_rs`：提供ArkTS和Rust交互能力；
- `Node-API`：napi接口，实现ArkTS和C/C++交互能力；

**图 2**  ohos_napi_rs 内部架构图

![runtime_framework](./figures/framework.png)

`ohos_napi_rs` 内部主要分为三个模块:

- `Rust sys`：使用Rust CFFI封装底层napi接口；
- `Rust napi`：实现Rust数据类型和ArkTS数据类型相互转换；提供Rust函数注册进ArkTS的逻辑；
- `Rust macro`：提供用户使用的过程宏，如#[napi]，自动完成ArkTS和Rust数据类型转换、Rust函数注册功能；

## 目录
```
ohos_napi_rs
├── crates
│   ├── backend
│   │   └── src                     # 过程宏底层实现逻辑
│   │       ├── codegen             # 过程宏自动生成类型转换、函数注册代码
│   │       └── typegen             # 过程宏自动生成ArkT函数头文件逻辑(d.ts)
│   ├── build
│   │   └── src                     # 编译脚本
│   ├── macro
│   │   └── src                     # 过程宏对外接口实现
│   │       ├── expand              # 过程宏对外接口
│   │       └── parser              # 过程宏TokenStream解析
│   ├── napi
│   │   └── src
│   │       ├── bindgen_runtime     # Rust函数注册、类型转换
│   │       │   └── js_values       # Rust原生数据类型和ArkTS类型转换逻辑实现，如Rust(String)对应ArkTS(string)
│   │       └── js_values	        # Rust安全引用类型和ArkTS类型转换逻辑实现	，如Rust(JsString)对应ArkTS(string)			
│   │           └── string 			# Rust String类型，如latin1、utf16、utf8
│   └── sys
│       └── src						# Rust CFFI封装底层napi接口
├── docs                            # 使用文档
└── figures                         # 架构图
```

## 编译构建

### 使用Cargo编译

1. 环境准备，安装Rust和ohos-sdk。

   Rust需要保证版本 >= 1.78.0，并且安装OpenHarmony对应的toolchain。

   ```shell
   rustup target add aarch64-unknown-linux-ohos
   rustup target add armv7-unknown-linux-ohos
   rustup target add x86_64-unknown-linux-ohos
   ```

   ohos-sdk可以从[每日构建](https://ci.openharmony.cn/workbench/cicd/dailybuild/dailylist)获取，ohos-sdk中包含native库和编译工具链。

2. 新建Rust工程，在 `Cargo.toml` 中引入 `ohos_napi_rs`，设置Rust输出库类型为cdylib。

   ```toml
   [dependencies]
   napi = {path = "ohos_napi_rs/crates/napi"}
   napi-derive = {path = "ohos_napi_rs/crates/macro"}
   
   [build-dependencies]
   napi-build = {path = "ohos_napi_rs/crates/build"}
   
   [lib]
   crate-type=["cdylib"]
   ```

3. 添加Rust构建脚本build.rs。

   ```rust
   // build.rs
   fn main() {
     napi_build::setup();
   }
   ```

4. 开发Rust代码。

   ```rust
   use napi_derive::napi;
   
   #[napi]
   fn add(a: u32, b: u32) -> u32 {
     a + b
   }
   ```

5. 设置Rust构建时使用的linker，在工程项目中新建.cargo/config.toml文件。

   参考[Rust官方文档](https://doc.rust-lang.org/rustc/platform-support/openharmony.html)

   ```toml
   [target.x86_64-unknown-linux-ohos]
   linker = "/path/to/x86_64-unknown-linux-ohos-clang.sh"
   
   [target.armv7-unknown-linux-ohos]
   linker = "/path/to/armv7-unknown-linux-ohos-clang.sh"
   
   [target.aarch64-unknown-linux-ohos]
   linker = "/path/to/aarch64-unknown-linux-ohos-clang.sh"
   ```

   创建以下shell脚本，从ohos-sdk中封装编译工具链：

   x86_64-unknown-linux-ohos-clang.sh：

   ```shell
   #!/bin/sh
   exec /path/to/ohos-sdk/linux/native/llvm/bin/clang \
     -target x86_64-linux-ohos \
     --sysroot=/path/to/ohos-sdk/linux/native/sysroot \
     -Wl --no-undefined \
     -D__MUSL__ \
     "$@"
   ```

   armv7-unknown-linux-ohos：

   ```shell
   #!/bin/sh
   exec /path/to/ohos-sdk/linux/native/llvm/bin/clang \
     -target arm-linux-ohos \
     --sysroot=/path/to/ohos-sdk/linux/native/sysroot \
     -Wl --no-undefined \
     -D__MUSL__ \
     -march=armv7-a \
     -mfloat-abi=softfp \
     -mtune=generic-armv7-a \
     -mthumb \
     "$@"
   ```

   aarch64-unknown-linux-ohos-clang.sh：

   ```shell
   #!/bin/sh
   exec /path/to/ohos-sdk/linux/native/llvm/bin/clang \
     -target aarch64-linux-ohos \
     --sysroot=/path/to/ohos-sdk/linux/native/sysroot \
     -Wl --no-undefined \
     -D__MUSL__ \
     "$@"
   ```

   使用cargo命令进行编译：

   ```
   cargo build --target x86_64-unknown-linux-ohos --release
   cargo build --target armv7-unknown-linux-ohos --release
   cargo build --target aarch64-unknown-linux-ohos --release
   ```

6. 将Rust编译生成的so以预构建库的方式添加到ArkTS工程中，添加到以下对应平台的目录中，如果没有文件夹就新建。

   ```
   arktsProject/entry/libs/arm64-v8a
   arktsProject/entry/libs/armeabi-v7a
   arktsProject/entry/libs/x86_64
   ```

   在arkts工程中添加头文件声明，并调用Rust函数。

   index.d.ts

   ```
   export declare function add(a: number, b: number): number;
   ```

   Index.ets

   ```js
   import rustNapi from 'libarkts_napi_sdv.so';
   
   let res: number = rustNapi.add(2, 4);
   expect(res).assertEqual(6);
   ```

## 用户指南

详细内容请见[用户指南](./docs/user_guide.md)

## 致谢

本库基于[napi-rs](https://github.com/napi-rs/napi-rs)仓库进行适配，完成ArkTS和Rust的互通功能。同时也参考了[ohos-rs](https://github.com/ohos-rs/ohos-rs)的实现设计，在此对napi-rs和ohos-rs表示感谢。