> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arkffi.hmbill.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Install arkffi and call your first C function

<Steps>
  <Step title="Prerequisites">
    Before you begin, make sure you have:

    * HarmonyOS (API 12+) device or emulator
    * DevEco Studio with HarmonyOS SDK
    * A `.so` shared library (pre-built or compiled from source)

    **Architecture support:**

    | Architecture | ABI         | Notes                                                                    |
    | ------------ | ----------- | ------------------------------------------------------------------------ |
    | ARM64        | `arm64-v8a` | Default, verified                                                        |
    | x86\_64      | `x86_64`    | Add `x86_64` to `abiFilters`                                             |
    | RISC-V 64    | `riscv64`   | External toolchain; DevEco Studio does not support RISC-V build natively |
  </Step>

  <Step title="Install arkffi">
    ```bash theme={null}
    ohpm install arkffi
    ```
  </Step>

  <Step title="Import and use">
    ```typescript theme={null}
    import { dlopen, FFIType, CString, CFunction, JSCallback } from 'arkffi';

    const lib = dlopen('libmylib.so', {
      calculate: {
        args: [FFIType.int32, FFIType.double, FFIType.CString],
        returns: FFIType.double,
      },
    });

    lib.symbols.calculate(42, 3.14, 'hello');
    lib.close();
    ```
  </Step>

  <Step title="Use the raw bridge">
    For lower-level control, use the NAPI functions directly:

    ```typescript theme={null}
    import ffi from 'liblibrary.so';

    const handle = ffi.load('libffi_target.so');
    ffi.defineFunction(handle, 'add', 'dd', 'd');
    const sum = ffi.callBySig(handle, 'add', [2.0, 3.0], []);
    ffi.close(handle);
    ```
  </Step>

  <Step title="Work with C pointers">
    ```typescript theme={null}
    const ptr = ffi.getSymbolPtr(handle, 'add');

    ffi.callPtr(ptr, 'dd', 'd', [2.0, 3.0], []);

    const cstr = new CString(ptr);
    cstr.toString();
    cstr.length;
    ```
  </Step>

  <Step title="Create callbacks">
    ```typescript theme={null}
    const cb = new JSCallback(
      (a: number, b: number): number => a + b,
      { args: [FFIType.int32, FFIType.int32], returns: FFIType.int32 },
    );

    cb.call(2, 3);   // → 5
    cb.ptr;          // → slot handle or trampoline address
    cb.close();
    ```
  </Step>
</Steps>