# cmake_for_arkui_napi

**Repository Path**: aree-go/cmake_for_arkui_napi

## Basic Information

- **Project Name**: cmake_for_arkui_napi
- **Description**: No description available
- **Primary Language**: C++
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 4
- **Created**: 2025-10-10
- **Last Updated**: 2025-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CMAKE for Arkui_napi

## 获取源码

1. 下载 ark_standlone_build 作为基础开发环境.

   [ArkCompiler Standlone build](https://gitee.com/ark_standalone_build/docs)

   1. 安装依赖软件包

      ```bash
      sudo apt-get update
      sudo apt-get install python-is-python3 python3-requests \
         python3-pip ruby git-lfs gcc-multilib g++-multilib \
         zlib1g-dev libc++1 curl nodejs ccache cmake
      ```

   2. 安装repo工具

      ```bash
      mkdir -p ~/.local/bin
      curl https://gitee.com/oschina/repo/raw/fork_flow/repo-py3 -o ~/.local/bin/repo
      chmod +x ~/.local/bin/repo

      # 为使配置持久化，简化后续使用流程，你可能需要将该行内容shell配置文件
      # 常见shell配置文件如下：
      # bash/sh -> ~/.bashrc
      # zsh -> ~/.zshrc
      export PATH=~/.local/bin:$PATH
      ```

   3. 配置git用户信息

      ```bash
      git config --global user.email <youremail@example.com>
      git config --global user.name <your name>
      ```

   4. 拉取代码

      > \<workspace\> 表示你创建的用来容纳代码的文件夹，下同。

      ```bash
      mkdir <workspace>
      cd <workspace>
      repo init -u https://gitee.com/ark-standalone-build/manifest.git -b master
      repo sync -c -j16
      repo forall -c 'git lfs pull'
      ```

   5. 安装编译器及二进制工具

      ```bash
      ./prebuilts_download.sh
      ```

2. 下载源码

   如下代码，均在 \<workspace\> 目录下执行

   通过https

   ```bash
   git clone https://gitee.com/milkpotatoes/cmake_for_arkui_napi.git -b master
   ```

   或ssh

   ```bash
   git clone git@gitee.com:milkpotatoes/cmake_for_arkui_napi.git -b master
   ```

3. 下载三方模块

   ```bash
   cd cmake_for_arkui_napi
   git submodule init
   git submodule update
   ```

## 编译构建

   Usage:

   ```bash
   ./build.sh x64 # 产物 build/release
   # 使用 --debug 参数编译 debug 版本
   ./build.sh --debug x64 # 产物 build/debug

   # 使用缓存快速重编模块代码（适用于未修改arkui_napi模块代码）
   ./build.sh --cache x64
   ```

   更多命令参数请使用参数`-h`运行编译脚本查看。

## 执行测试用例

前置条件：完成napi_runner的编译

- 执行所有测试套或符合指定特征的测试套：

   ```bash
   # 如下命令工作路径为仓库根目录, 其他路径执行请相应更改run.py的路径
   ./tests/run.py --build-dir <BUILD_DIR> --es2abc-path </path/to/es2abc>
   ./tests/run.py --build-dir <BUILD_DIR> --ark-build-dir <ARK_BUILD_DIR> [--filter <filter>] [--ark-options <ARK_OPTIONS>] [--level <LEVEL>]
   # 示例：
   # ./tests/run.py -b build/x64-linux.release/ -e ./es2abc
   # ./tests/run.py -b build/x64-linux.release/ -e ./es2abc --filter "base64*"
   # ./tests/run.py -b build/x64-linux.release/ -e ./es2abc --ark-options compiler-enable-jit=true
   # ./tests/run.py -b build/x64-linux.release/ -e ./es2abc -l L0
   ```

- 手动执行指定测试套：

   - 复用自动脚本的编译结果

   ```bash
   cd <BUILD_DIR/tests> # BUILD_DIR与传递给脚本的路径一致
   ../napi_runner <testsuit.test.abc> [level | testcases...]
   # 用法示例
   # ../napi_runner base64.test.abc # 执行base64测试套所有测试用例
   # ../napi_runner base64.test.abc L0 # 执行base64测试套所有L0级别用例
   # ../napi_runner base64.test.abc L1 # 执行base64测试套所有L1及以上级别（L0、L1）用例
   # ../napi_runner base64.test.abc Base64Test # 执行base64测试套指定用例
   # ../napi_runner base64.test.abc Base64Test basicAsciiEncode # 执行base64测试套指定用例（多个）
   ```

   - 手动编译并执行

   ```bash
   cd tests
   for f in {utils/test-framework.ts,utils/test-util.ts}; do
      ../es2abc --module $f --output /path/to/output/$f;
   done
   ../es2abc --module <test-suit.test.ts> --output /path/to/output/<test-suit.test.abc>
   # 执行与复用编译结果一致，略
   ```

## 贡献

fork本仓库，将代码提交到您的仓库后，在本项目创建pull request。

## 创建并使用native插件

### 从模板工程快速创建

demo目录将会加入工程编译，工程编译完成，即会完成插件的编译。

```shell
   cp demo/template/* demo/
```

### 在js代码中加载插件

```js
   // 路径可以使用绝对路径或相对路径, 相对路径将从可执行文件运行时的工作路径进行加载
   // 仅当模块首次被加载即通过 requireNapi 方法被加载时, 插件才可以成功的被加载
   const myAddon = requireNapi("<path/to/addon>");
```

## 运行js/ts

   使用预定义的脚本

   ```bash
   # runtime_args 与 napi_runner 约束保持一致，暂不支持调整 es2abc 编译编译选项
   ./run_script.sh [runtime_args...] <file_name> [execute_args...]
   ```

   或手动将js/ts编译为abc文件，然后执行

   ```bash
   ./es2abc --module <file_name>.ts
   ./napi_runner <file_name>.abc
   ```

## 支持的能力

1. 支持的类方法

   1. AbortController
   2. AbortSignal
   3. Event
   4. EventTarget
   5. File
   6. FormData
   7. Headers
   8. TextEncoder
   9. TextDecoder
   10. URL
   11. URLSearchParams

2. 支持的普通方法

   1. atob
   2. btoa
   3. setTimeout
   4. setInterval
   5. console
   6. clearTimeout
   7. clearInterval
   8. requireNapi

      > - 声明：`requireNapi(path, baseDiur?): any`
      > - 参数：
      >    - path：Node-API模块路径。
      >    - （可选）baseDir：查找模块的路径，若path为绝对路径，该参数将会被忽略。
      >       默认值：`RequireBaseDir.DEFAULT`，从工作目录或请求加载模块的js文件所在文件夹开始查找。

      ```ts
      enum RequireBaseDir {
         DEFAULT = 0,
         WORK_DIR = 1 << 0,        // 工作目录
         SCRIPT_DIR = 1 << 1,      // js文件所在文件夹
         BUILD_DIR = 1 << 2,       // 编译产物文件夹
         EXECUTABLE_DIR = 1 << 3,  // napi_runner所在文件夹
      };
      ```

   9. preLoad
      
      参数约束与`requireNapi`相同，但该接口将在子线程内进行so的预加载，但不会尝试初始化模块对象。

   10. queueMicrotask
   11. execute

      执行一个ArkByteCode文件

3. 其他能力

   1. process
   
其他注意事项

使用非`utf-8`、`utf-16`编码构造`TextDecoder`需额外指定`-k --icu-data-path=<path/to/icudata>`参数，若无可用的icu data，参考如下命令进行编译。

```bash
   cd <PATH/TO/ARK/REPO>/third_party/icu/icu4c/source
   ./configure --with-data-packaging=archive
   # 产物路径 <PATH/TO/ARK/REPO>/third_party/icu/icu4c/source/data/out/icudt72l.dat
   make
```