> ## 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.

# 快速開始

> 安裝 arkffi 並調用你的第一個 C 函數

<Steps>
  <Step title="前置條件">
    開始之前，請確保你已準備好：

    * HarmonyOS（API 12+）設備或模擬器
    * DevEco Studio 和 HarmonyOS SDK
    * 一個 `.so` 共享庫（預編譯或從源碼編譯）

    **架構支援：**

    | 架構        | ABI         | 說明                                   |
    | --------- | ----------- | ------------------------------------ |
    | ARM64     | `arm64-v8a` | 預設支援，已驗證                             |
    | x86\_64   | `x86_64`    | 需在 `abiFilters` 中新增                  |
    | RISC-V 64 | `riscv64`   | 需外部工具鏈；DevEco Studio 不直接支援 RISC-V 構建 |
  </Step>

  <Step title="添加 library 模塊">
    在項目中添加 HAR 模塊：

    ```
    Project/
    └── library/
        ├── src/main/cpp/          # 原生 C++ 代碼
        ├── src/main/ets/          # ArkTS/TS 封裝
        ├── build-profile.json5
        └── oh-package.json5
    ```
  </Step>

  <Step title="配置原生構建">
    ```json filename="library/build-profile.json5" theme={null}
    {
      "buildOption": {
        "externalNativeOptions": {
          "path": "./src/main/cpp/CMakeLists.txt",
          "abiFilters": ["arm64-v8a", "x86_64", "riscv64"]
        }
      }
    }
    ```

    ```cmake filename="library/src/main/cpp/CMakeLists.txt" theme={null}
    cmake_minimum_required(VERSION 3.5.0)
    add_library(library SHARED napi_init.cpp)
    target_link_libraries(library PUBLIC libace_napi.z.so)
    ```
  </Step>

  <Step title="導入並使用">
    ```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="使用原始橋接">
    需要更底層的控制時，可直接使用 NAPI 函數：

    ```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="操作 C 指針">
    ```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="創建回調">
    ```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;          // → 槽位句柄
    cb.close();
    ```
  </Step>
</Steps>