External Pre-built Libraries

This guide demonstrates how to integrate a C/C++ library compiled externally (e.g., with CLion or CMake) into an arkffi project and call its functions via dlopen.

Overview

Create a C/C++ library project
Cross-compile for HarmonyOS arm64-v8a using the NDK
Place the compiled .so into entry/libs/arm64-v8a/
Load and call it from ArkTS via dlopen

1. Create the External Library

Source library.cpp:

#ifdef __cplusplus
extern "C" {
#endif

    const char* hello(void) {
        return "Hello, World!";
    }

#ifdef __cplusplus
}
#endif

extern "C" prevents C++ name mangling, ensuring dlsym("hello") can find the symbol. Without it, the symbol would be mangled to _Z5hellov and dlopen would fail.

CMakeLists.txt:

cmake_minimum_required(VERSION 3.3)
project(hello)
set(CMAKE_CXX_STANDARD 14)
add_library(hello SHARED library.cpp)

2. Cross-Compile for HarmonyOS

export TOOLCHAIN=/path/to/ohos-sdk/native/llvm
export SYSROOT=/path/to/ohos-sdk/native/sysroot

$TOOLCHAIN/bin/aarch64-linux-ohos-clang++ \
  --sysroot=$SYSROOT \
  -fPIC -shared \
  -o libhello.so \
  library.cpp

3. Place the Output

entry/libs/arm64-v8a/libhello.so

If your project also supports x86_64 emulator, place the corresponding .so under entry/libs/x86_64/ as well.

4. Configure abiFilters

Ensure library/build-profile.json5 contains the target architecture in abiFilters:

{
  "buildOption": {
    "externalNativeOptions": {
      "path": "./src/main/cpp/CMakeLists.txt",
      "abiFilters": ["arm64-v8a"]
    }
  }
}

5. Call from ArkTS

import { dlopen, FFIType, CString, CFunction, JSCallback, Library } from 'arkffi';

const libhello = dlopen('libhello.so', {
  hello: { args: [], returns: FFIType.int64 },
});

const resultPtr = libhello.symbols.hello();
const resultStr = new CString(resultPtr);

console.log(resultStr.toString()); // -> "Hello, World!"

libhello.close();

Important Notes

Functions returning const char* must use returns: FFIType.int64 (to get the pointer), not FFIType.CString.
Use CString to read the actual string content from the pointer.
Ensure the library uses extern "C" to avoid name mangling.

Troubleshooting

Problem	Cause	Solution
`dlsym failed: Symbol not found`	C++ name mangling	Add `extern "C"` in source
`cannot locate library`	`.so` not in correct path	Check `entry/libs/${OHOS_ARCH}/` path
`cannot locate symbol`	Wrong toolchain for compilation	Use HarmonyOS NDK, not host system compiler
Call returns empty string	Wrong return type	Use `FFIType.int64`, not `FFIType.CString`

Getting Started

API Reference

Guides

Examples

External Pre-built Libraries

Overview

1. Create the External Library

2. Cross-Compile for HarmonyOS

3. Place the Output

4. Configure abiFilters

5. Call from ArkTS

Important Notes

Troubleshooting

​Overview

​1. Create the External Library

​2. Cross-Compile for HarmonyOS

​3. Place the Output

​4. Configure abiFilters

​5. Call from ArkTS

​Important Notes

​Troubleshooting

Overview

1. Create the External Library

2. Cross-Compile for HarmonyOS

3. Place the Output

4. Configure abiFilters

5. Call from ArkTS

Important Notes

Troubleshooting