Skip to main content

HarmonyOS setup

Before creating or building an OHOS project, set up the OpenHarmony Flutter toolchain. The full environment guide is maintained by the OpenHarmony Flutter team:

Follow that guide to install DevEco Studio, JDK 17, the OHOS-enabled Flutter SDK, the OpenHarmony SDK, and the required ohpm, hvigor, node, and hdc tools. After configuring the toolchain, run:

flutter doctor -v

Both Flutter and OpenHarmony should be reported as available. If the doctor output reports a missing OpenHarmony component, finish the corresponding setup step from the environment guide before continuing.

OHOS_SDK_HOME​

In addition to the variables required by the OpenHarmony Flutter guide, flutter_rust_bridge needs OHOS_SDK_HOME when CargoKit cross-compiles Rust code for OHOS. Set it to the SDK's native directory, not to the SDK root.

On Windows, add or update an environment variable named OHOS_SDK_HOME. It can be either a user environment variable or a system environment variable, as long as the terminal and IDE used for building can read it. Its value should be the SDK native directory, for example D:\Huawei\SDK\18\native.

On macOS or Linux, add this to your shell profile, such as ~/.bashrc, ~/.zshrc, or ~/.profile, so the variable persists after restarting the terminal:

export OHOS_SDK_HOME=/opt/Huawei/SDK/18/native

The OHOS_SDK_HOME path must not contain Chinese characters, spaces, or other whitespace characters. Otherwise the Rust build invoked by CargoKit may fail before or during native compilation.

This is especially important when using the SDK bundled with DevEco Studio: some default DevEco Studio installation paths contain spaces, and the bundled SDK inherits that path. Install or move DevEco Studio and the SDK to a directory whose full path is plain ASCII without whitespace, or configure DevEco Studio to use an SDK directory such as D:\Huawei\SDK\18\native.

Restart your terminal and IDE after changing the environment variable, then confirm the value before building:

echo $OHOS_SDK_HOME

On Windows PowerShell, use:

echo $env:OHOS_SDK_HOME

Creating an OHOS project​

danger

If your project uses FVM to manage Flutter versions, always pass --skip-fvm-install when running flutter_rust_bridge commands for an OHOS project.

HarmonyOS/OpenHarmony Flutter is a Huawei community fork of Flutter. Official Flutter does not support OHOS, but FVM installs Flutter from the official Flutter releases by default. Without --skip-fvm-install, FVM may try to fetch an official Flutter SDK, which can get stuck or leave the OHOS project unable to run.

After the HarmonyOS toolchain is ready, create the project with OHOS enabled:

flutter_rust_bridge_codegen create my_app --platforms ohos --skip-fvm-install

If you also want the usual Flutter mobile platforms, include them explicitly:

flutter_rust_bridge_codegen create my_app --platforms android,ios,ohos --skip-fvm-install

Use the same flag when integrating flutter_rust_bridge into an existing OHOS project:

flutter_rust_bridge_codegen integrate --platforms ohos --skip-fvm-install

Then build or run the generated Flutter project with the OHOS Flutter toolchain, for example:

cd my_app
flutter build hap --debug

If the Rust build fails with an OHOS SDK error, check OHOS_SDK_HOME first. It must point to the native SDK directory and the full path must not contain Chinese characters or whitespace.