Build for HarmonyOS

The 1.2.4 Release includes both the native C/C++ SDK and an ArkTS HAR project with a compiled native library. Choose the HAR project for an ArkTS app; choose the native SDK when you provide your own native integration. Build from source when you need to change the native implementation or build configuration.

The package and configurations below use InspireFace 1.2.4, target arm64-v8a, and run CPU inference with raw pixel buffers for image input. Validate the packaged app on the devices you plan to support.

Download the prebuilt SDK

Download the HarmonyOS 1.2.4 ZIP:

curl -fL -o inspireface-harmonyos-arm64-v8a-1.2.4.zip \
  https://github.com/HyperInspire/InspireFace/releases/download/v1.2.4/inspireface-harmonyos-arm64-v8a-1.2.4.zip
unzip inspireface-harmonyos-arm64-v8a-1.2.4.zip

The extracted directory contains:

inspireface-harmonyos-arm64-v8a-1.2.4/
  InspireFace/
    include/
    lib/libInspireFace.so
  HarmonyOS/
    libs/arm64-v8a/libinspireface_napi.so
    har/
      Index.ets
      oh-package.json5
      src/main/ets/InspireFace.ets
      src/main/cpp/types/libinspireface_napi/
      src/main/libs/arm64-v8a/libinspireface_napi.so
  version.txt

For ArkTS, go straight to adding the HAR to an app using HarmonyOS/har. This is a HAR project directory with the .so already compiled; DevEco Studio/Hvigor packages it for your app. It does not require the separate InspireFace/lib/libInspireFace.so. For native C/C++, use that core library and its matching InspireFace/include headers. Download the model pack separately.

Prepare the Native SDK

Complete source preparation, then install an OpenHarmony Native SDK, CMake 3.20 or newer, Make and Node.js. The HAR script in the current v1.2.4 release passes -DCMAKE_POLICY_VERSION_MINIMUM=3.5 for dependencies with older policy settings under CMake 4. DevEco Studio is used later to integrate and package the HAR module.

Set OHOS_NATIVE_HOME to the Native SDK directory containing the toolchain file:

export OHOS_NATIVE_HOME=/absolute/path/to/native-sdk/native
test -f "$OHOS_NATIVE_HOME/build/cmake/ohos.toolchain.cmake"
cmake --version
node --version

Without this variable, the scripts look under build/harmony-tools/openharmony-6.1/native-sdk/native inside the repository. They do not download that SDK automatically.

The source tree includes cmake/ohos/node_modules/@ali/tcpkg/tcpkg.cmake, which supplies the packaging hook expected by MNN's OHOS configuration. The build scripts set NODE_PATH to this directory. Keep it with the rest of the source preparation; no separate tcpkg installation is needed for this path.

Build the ArkTS module

From the InspireFace repository root:

bash command/build_harmonyos_napi.sh

The script builds the InspireFaceNapi target, installs it and strips the installed library. The native core and third-party dependencies are linked into libinspireface_napi.so; the HAR does not need a second libInspireFace.so.

build/inspireface-harmonyos-napi-arm64-v8a/install/HarmonyOS/
  libs/arm64-v8a/libinspireface_napi.so
  har/
    Index.ets
    oh-package.json5
    build-profile.json5
    hvigorfile.ts
    src/main/
      module.json5
      ets/InspireFace.ets
      cpp/types/libinspireface_napi/
        index.d.ts
        oh-package.json5
      libs/arm64-v8a/libinspireface_napi.so

har/ is a staged HAR project directory containing the compiled library and ArkTS sources. Package it as a HAR through the application's normal DevEco Studio/Hvigor workflow.

Add the HAR to an app

Copy the Release package's HarmonyOS/har/ directory, or the installed har/ from a source build, into your DevEco Studio app as an inspireface module. Register that module in the project and add a local dependency from the entry module. For sibling entry/ and inspireface/ directories, use:

{
  "dependencies": {
    "@hyperinspire/inspireface": "file:../inspireface"
  }
}

Sync the project dependencies, then build the app or HAR using the selected DevEco SDK and your project's Hvigor configuration. Keep Index.ets, the ArkTS wrapper, native declarations and compiled .so together when distributing the module.

The harmony/inspireface/ source directory is the template for this package. Use HarmonyOS/har/ from the Release ZIP or the installed har/ directory from a source build; both contain the native library as well as the wrapper.

Both oh-package.json5 manifests must match the native SDK version. The CMake configuration checks the top-level module manifest and the libinspireface_napi type-package manifest against the source version (1.2.4 in this checkout). Upgrade these pieces together when changing SDK versions.

Put the model pack in an app-readable file location. If you bundle it as a raw resource, copy it to the app's files directory before launch. The HarmonyOS integration guide includes an ArkTS detection example and worker-lifetime rules.

Build the native SDK only

For a native application or a custom bridge:

bash command/build_harmonyos.sh

The standard configuration builds libInspireFace.so and installs the C headers:

build/inspireface-harmonyos-arm64-v8a/install/
  InspireFace/
    include/
    lib/libInspireFace.so
  version.txt

Use that library and its matching headers in your native target. This output does not contain the ArkTS module. For ArkTS, use the Node-API build above so that the native exports, declarations and wrapper are packaged together.

Build locations and checks

The HarmonyOS scripts do not use VERSION for output names. Set the appropriate build-directory variable if you want a versioned directory:

OHOS_NAPI_BUILD_DIR="$PWD/build/harmonyos-napi-1.2.4" \
OHOS_BUILD_JOBS=4 \
  bash command/build_harmonyos_napi.sh

The Node-API target runs checks after linking: the library must be AArch64, register its Node-API module, depend on libace_napi.z.so, keep the core C API hidden, and avoid Android-only libraries. A separate contract check covers the C API, native bridge, type declarations and ArkTS wrapper.

After packaging, check model launch, one RGBA detection, result release and shutdown on a target device. Then test camera format conversion and worker scheduling in the app. See HarmonyOS usage for the complete flow.

Source: native build script, Node-API build script, HAR install and version checks.