Ohos Rs

https://ohos.rs/en/docs/
Admin
ohos-rs is a project that adapted napi-rs for the HarmonyOS runtime, addressing subtle logic...
Tokens:4,413
Snippets:78
Trust Score:5.4
Update:3 months ago
Show doc for...
Tokens:
Raw
### Project file structure example

Source: https://ohos.rs/en/docs/basic/simple-project

An example of the expected project file structure after initialization and setup.

```txt
.
├── Cargo.lock
├── Cargo.toml
├── build.rs
└── src
    └── lib.rs
```

--------------------------------

### Setup build script with napi-build-ohos

Source: https://ohos.rs/en/docs/basic/simple-project

Create a `build.rs` file to execute `napi_build_ohos::setup()` before the project builds, enabling custom build logic.

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

--------------------------------

### Install Rust

Source: https://ohos.rs/en/docs/basic/quick-start

Installs the Rust programming language using the official installation script. Ensure you have curl installed.

```shell
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

--------------------------------

### Install ohrs CLI Tool

Source: https://ohos.rs/en/docs/basic/quick-start

Installs the ohrs command-line interface tool using Cargo, the Rust package manager. This tool simplifies project management for HarmonyOS.

```shell
cargo install ohrs
```

--------------------------------

### Build a Project with ohrs

Source: https://ohos.rs/en/docs/basic/quick-start

Builds the current HarmonyOS project using the ohrs CLI tool. The command expects a build file, such as 'build.md' in this example.

```shell
ohrs build.md
```

--------------------------------

### Set HarmonyOS NDK Environment Variable

Source: https://ohos.rs/en/docs/basic/quick-start

Sets the OHOS_NDK_HOME environment variable to point to your HarmonyOS NDK installation directory. Adjust the path based on your SDK version and installation location.

```shell
# For 4.0 or older version
export OHOS_NDK_HOME=/path/Sdk/9/

# For 5.0 or newer version
export OHOS_NDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony
```

--------------------------------

### Define Callback Parameter for TSFN

Source: https://ohos.rs/en/docs/usage/tsfn

Defines a parameter for the callback function that will be invoked after multithreaded execution is completed. This is the initial setup for using TSFN.

```rust
use napi_derive_ohos::napi;
use napi_ohos::{JsFunction, Result};

#[napi]
pub fn run_ts_fn(cb: JsFunction) -> Result<()>  {
  Ok(())
}
```

--------------------------------

### JavaScript Usage of TSFN Callback

Source: https://ohos.rs/en/docs/usage/tsfn

Example of how the JavaScript code would interact with the native function that uses TSFN. It shows calling the native function and handling the result in the callback.

```typescript
import tslib from 'libts_fn.so';

tslib.runTsFn((result) => {
    console.log(result);
    // result is 1;
});
```

--------------------------------

### Initialize a New Project with ohrs

Source: https://ohos.rs/en/docs/basic/quick-start

Initializes a new HarmonyOS project named 'hello' using the ohrs CLI tool. This command sets up the basic project structure.

```shell
ohrs init hello
```

--------------------------------

### Initialize a new project

Source: https://ohos.rs/en/docs/cli/init

Use the 'ohrs init' command followed by a project name to create a new project folder. This name will also be used as the project's name in Cargo.toml.

```shell
ohrs init xx
```

--------------------------------

### Specify Output Directory

Source: https://ohos.rs/en/docs/cli/build

Builds the project and places the final binary in a custom folder named 'new_folder'.

```shell
cargo build --dist new_folder
```

--------------------------------

### Build with Compact Output

Source: https://ohos.rs/en/docs/cli/build

Builds the project with a compact output structure, placing all final binaries in a single folder.

```shell
ohrs build --compact
```

--------------------------------

### Initialize a new Rust binary project

Source: https://ohos.rs/en/docs/basic/simple-project

Use Cargo to create a new Rust project. This command initializes a library project.

```shell
cargo new hello --lib
```

--------------------------------

### Basic Build Command

Source: https://ohos.rs/en/docs/cli/build

The standard command to build the final binary and generate .d.ts files.

```shell
ohrs build
```

--------------------------------

### Build in Release Mode

Source: https://ohos.rs/en/docs/cli/build

Builds the project with optimizations enabled by setting the 'release' option to true.

```shell
ohrs build --release
```

--------------------------------

### Configure Cargo.toml for cdylib

Source: https://ohos.rs/en/docs/basic/simple-project

Set the crate type to `cdylib` in `Cargo.toml` to produce a dynamic library suitable for HarmonyOS.

```toml
# Cargo.toml

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

--------------------------------

### Control Binary Stripping

Source: https://ohos.rs/en/docs/cli/build

Demonstrates enabling and disabling the 'strip' option to control the use of 'llvm-strip' for reducing binary file size.

```shell
# enabled
cargo build --strip

# disabled
cargo build --strip=false
```

--------------------------------

### Add NAPI and build dependencies

Source: https://ohos.rs/en/docs/basic/simple-project

Add essential dependencies for NAPI integration and building for HarmonyOS. The `napi-build-ohos` dependency is added as a build dependency.

```shell
cargo add napi-ohos napi-derive-ohos

cargo add napi-build-ohos --build
```

--------------------------------

### Generated Cargo.toml structure

Source: https://ohos.rs/en/docs/cli/init

When a project is initialized, the Cargo.toml file is created with default settings, including the project name derived from the init command.

```toml
[package]
name    = "xx"
version = "0.1.0"
edition = "2021"

```

--------------------------------

### Implement NAPI add method

Source: https://ohos.rs/en/docs/basic/simple-project

Define a NAPI-exposed function `add` using the `napi` derive macro. This function takes two u32 arguments and returns their sum.

```rust
use napi_derive_ohos::napi;

#[napi]
pub fn add(a: u32,b: u32) -> u32 {
    a + b
}
```

--------------------------------

### Generate ohpm Package

Source: https://ohos.rs/en/docs/cli/artifact

Standard command to generate a package for ohpm.

```shell
ohrs artifact
```

--------------------------------

### Link libc++ or libclang_rt.builtins.a in Rust

Source: https://ohos.rs/en/docs/more/emu-tls

Use this build script to link the required C++ standard library or builtins library when emu-tls symbols are missing. This is necessary for LLVM versions 15 and above.

```rust
// build.rs

fn main() {
    println!("cargo:rustc-link-lib=c++");
    // or
    // println!("cargo:rustc-link-lib=static=clang_rt.builtins");
}
```

--------------------------------

### Using Fibonacci Task in ArkTS

Source: https://ohos.rs/en/docs/usage/task

Demonstrates how to import and use the `fib` function from the native module in an ArkTS application. The `await` keyword is used to handle the Promise returned by the function.

```typescript
import nativeFib from 'libfib.so';

const result = await nativeFib.fib(10);
```

--------------------------------

### Rust Function for Addition

Source: https://ohos.rs/en/docs/basic.html

This Rust code defines a simple addition function decorated with `#[napi]` to make it available for use in HarmonyOS.

```rust
use napi_derive_ohos::napi;

#[napi]
pub fn add(left: u32, right: u32) -> u32 {
  left + right
}
```

--------------------------------

### Add HarmonyOS Rust Targets

Source: https://ohos.rs/en/docs/basic/quick-start

Adds the necessary Rust toolchains for targeting different HarmonyOS architectures. These are required for cross-compilation.

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

--------------------------------

### Call TSFN from a Child Thread

Source: https://ohos.rs/en/docs/usage/tsfn

Demonstrates how to spawn a new thread and call the created TSFN from within it using non-blocking mode. The data passed to the TSFN is `Ok(1)`.

```rust
use std::thread;

use napi_derive_ohos::napi;
use napi_ohos::{
    threadsafe_function::{ErrorStrategy, ThreadsafeFunction, ThreadsafeFunctionCallMode},
    JsFunction, Result,
};

#[napi]
pub fn run_ts_fn(cb: JsFunction) -> Result<()> {
    let ts_fn: ThreadsafeFunction<i64, ErrorStrategy::CalleeHandled> = cb
        .create_threadsafe_function(0, |ctx| ctx.env.create_int64(ctx.value).map(|v| vec![v]))
        .unwrap();

    thread::spawn(move || {  
      ts_fn.call(Ok(1), ThreadsafeFunctionCallMode::NonBlocking);  
    });  

    Ok(())
}
```

--------------------------------

### Importing Buffer Module in ArkTS

Source: https://ohos.rs/en/docs/more/buffer

This is how you import the buffer module in ArkTS. Note that this module is not the same as the Node.js Buffer created through N-API.

```typescript
import { buffer } from "@kit.ArkTS"
```

--------------------------------

### Calling Rust Function from HarmonyOS

Source: https://ohos.rs/en/docs/basic.html

This TypeScript code demonstrates how to import and call the Rust `add` function from a HarmonyOS environment.

```typescript
import basic from 'libadd.so';

const result = basic.add(1,2);
// result is 3
```

--------------------------------

### Enable compiler-builtins weak intrinsics for x86_64

Source: https://ohos.rs/en/docs/more/emu-tls

Configure your Cargo project to enable weak intrinsics for the compiler builtins, which can resolve emu-tls errors on the x86_64 architecture. Add this to your .cargo/config.toml file.

```toml
[unstable]
build-std-features = ["compiler-builtins-weak-intrinsics"]
```

--------------------------------

### Create ThreadsafeFunction (TSFN)

Source: https://ohos.rs/en/docs/usage/tsfn

Creates a TSFN that can be safely called in a child thread. It accepts generic parameters for data type and response mode, and configuration for callback queue size and the execution callback function.

```rust
use napi_derive_ohos::napi;
use napi_ohos::{
    threadsafe_function::{ErrorStrategy, ThreadsafeFunction},
    JsFunction, Result,
};

#[napi]
pub fn run_ts_fn(cb: JsFunction) -> Result<()> {
    let ts_fn: ThreadsafeFunction<i64, ErrorStrategy::CalleeHandled> = cb 
        .create_threadsafe_function(0, |ctx| ctx.env.create_int64(ctx.value).map(|v| vec![v])) 
        .unwrap(); 

    Ok(())
}
```

--------------------------------

### Registering Fibonacci Task in Rust

Source: https://ohos.rs/en/docs/usage/task

Registers the `fib` method for ArkTS, which spawns a `ComputeFib` task and returns a JavaScript Promise object representing the asynchronous computation.

```rust
// register method
#[napi(ts_return_type="Promise<number>")]
pub fn fib(env: Env, init: u32) -> Result<JsObject> {
    let task = ComputeFib::new(init);
    let async_promise = env.spawn(task).unwrap();
    Ok(async_promise.promise_object())
}
```

--------------------------------

### ComputeFib Task Implementation

Source: https://ohos.rs/en/docs/usage/task

Implements the `Task` trait for the `ComputeFib` struct. The `compute` method calls the native Fibonacci function, and `resolve` creates a JsNumber from the result.

```rust
impl Task for ComputeFib {
    type Output = u32;
    type JsValue = JsNumber;

    fn compute(&mut self) -> Result<Self::Output> {
        Ok(fibonacci_native(self.n))
    }

    fn resolve(&mut self, env: Env, output: Self::Output) -> Result<Self::JsValue> {
        env.create_uint32(output)
    }
}
```

--------------------------------

### ComputeFib Struct Definition

Source: https://ohos.rs/en/docs/usage/task

A struct to hold the input value 'n' for the Fibonacci computation. It includes a constructor for easy initialization.

```rust
struct ComputeFib {
    n: u32,
}

impl ComputeFib {
    pub fn new(n: u32) -> ComputeFib {
        ComputeFib { n }
    }
}
```

--------------------------------

### Fibonacci Native Function

Source: https://ohos.rs/en/docs/usage/task

A recursive implementation of the Fibonacci sequence. This function is CPU-intensive and suitable for offloading to a background thread.

```rust
fn fibonacci_native(n: u32) -> u32 {
    match n {
        1 | 2 => 1,
        _ => fibonacci_native(n - 1) + fibonacci_native(n - 2),
    }
}
```

--------------------------------

### TypeScript Declaration for Fibonacci

Source: https://ohos.rs/en/docs/usage/task

Provides the TypeScript type definition for the `fib` function, indicating it takes a number and returns a Promise resolving to a number.

```typescript
// ts declare
export function fib(init: number): Promise<number>
```

--------------------------------

### Task Trait Definition

Source: https://ohos.rs/en/docs/usage/task

Defines the `Task` trait with methods for computation, resolution, rejection, and cleanup. This trait is fundamental for implementing asynchronous tasks in libuv threads.

```rust
pub trait Task: Send + Sized {
  type Output: Send + Sized + 'static;
  type JsValue: ToNapiValue + TypeName;

  /// Compute logic in libuv thread
  fn compute(&mut self) -> Result<Self::Output>;

  /// Into this method if `compute` return `Ok`
  fn resolve(&mut self, env: Env, output: Self::Output) -> Result<Self::JsValue>;

  /// Into this method if `compute` return `Err`
  fn reject(&mut self, _env: Env, err: Error) -> Result<Self::JsValue> {
    Err(err)
  }

  // after resolve or reject
  fn finally(&mut self, _env: Env) -> Result<()> {
    Ok(())
  }
}
```
Tokens:
Raw