方舟运行时使用指南

方舟编译器简介

方舟编译器(ArkCompiler)是为支持多种编程语言、多种芯片平台的联合编译、运行而设计的统一编译运行时平台。

• ArkCompiler主要分成两个部分：编译工具链与运行时。
• ArkCompiler eTS Runtime主要由四个子系统组成：Core Subsystem、Execution Subsystem、Compiler Subsystem、Runtime subsystem。
• ArkCompiler 的设计特点：原生支持类型、并发模型优化与并发API、安全。

要了解虚拟机的详细设计请参考 概述

环境搭建和编译

环境配置

搭建Ubuntu环境

• 初始环境软件安装（Ubuntu版本推荐18.04或20.04）

  sudo apt-get update
  sudo apt-get upgrade
  sudo apt-get install git-lfs git bison flex gnupg build-essential zip curl zlib1g-dev gcc-multilib g++-multilib libc6-dev-i386 lib32ncurses-dev x11proto-core-dev libx11-dev libc++1 lib32z1-dev ccache libgl1-mesa-dev libxml2-utils xsltproc unzip m4 libtinfo5 bc npm genext2fs liblz4-tool libssl-dev ruby openjdk-8-jre-headless gdb python3-pip libelf-dev libxcursor-dev libxrandr-dev libxinerama-dev

  详细Ubuntu安装搭建请参考 搭建Ubuntu环境

源码获取

下载源码请参考 下载说明

代码编译

注意：下列命令需在源码根目录下执行

1. 首次编译：

   ./build.sh --product-name rk3568

2. 首次编译后增量编译方舟运行时：

   编译linux-x86版本：

   ./build.sh --product-name rk3568 --build-target ark_js_host_linux_tools_packages

   编译oh-arm64版本：

   ./build.sh --product-name rk3568 --gn-args use_musl=true --target-cpu arm64 --build-target ark_js_packages

   编译oh-arm32版本:

   ./build.sh --product-name rk3568 --build-target  ark_js_packages

3. 首次编译后增量编译方舟前端：

   ./build.sh --product-name rk3568 --build-target ets_frontend_build

   更多编译命令请参考 编译命令

说明：上述编译命令为release版本，编译debug版本需增加编译选项：--gn-args is_debug=true。

方舟相关的二进制文件在如下路径：

out/rk3568/arkcompiler/runtime_core/
out/rk3568/arkcompiler/ets_frontend/
out/rk3568/arkcompiler/ets_runtime/
out/rk3568/clang_x64/arkcompiler/runtime_core/
out/rk3568/clang_x64/arkcompiler/ets_frontend/
out/rk3568/clang_x64/arkcompiler/ets_runtime

开发实例

本章节将介绍基于方舟运行时的开发测试实例。

HelloWorld

运行前准备

• 编译编译方舟运行时和方舟前端

  ./build.sh --product-name rk3568 --build-target ark_js_host_linux_tools_packages --build-target ets_frontend_build

运行hello-world.js

新建hello-world.js文件，写入以下源码：

print("Hello World!!!");

运行步骤：

1. 通过方舟前端生成hello-world.abc文件，编译命令：

   /your_code_path/out/rk3568/clang_x64/arkcompiler/ets_frontend/es2abc hello-world.js

2. 执行hello-world.abc文件：

   1. 设置搜索路径：

      export LD_LIBRARY_PATH=/your_code_path/out/rk3568/clang_x64/arkcompiler/ets_runtime:/your_code_path/prebuilts/clang/ohos/linux-x86_64/llvm/lib:/your_code_path/out/rk3568/clang_x64/thirdparty/zlib

   2. 执行ark_js_vm：

      /your_code_path/out/rk3568/clang_x64/arkcompiler/ets_runtime/ark_js_vm hello-world.abc

      执行结果如下：

      Hello World!!!

说明：此处“your_code_path”为源码目录路径。

反汇编hello-world.abc

编译生成反汇编工具：

./build.sh --product-name rk3568 --build-target arkcompiler/runtime_core:ark_host_linux_tools_packages

执行如下命令，结果输出到output.pa文件中：

/your_code_path/out/rk3568/clang_x64/arkcompiler/runtime_core/ark_disasm hello-world.abc output.pa

hello-world.abc反汇编结果如下：

#
# source binary: hello-world.abc
#

# ====================
# LITERALS

# ====================
# RECORDS

.record _ESAnnotation <external>

.record _ESModuleMode {
	u8 isModule
}

# ====================
# METHODS

.function any func_main_0_any_any_any_any_(any a0, any a1, any a2) <static> {
	mov v2, a2
	mov v1, a1
	mov v0, a0
	builtin.acc
	sta v5
	builtin.idi "print", 0x0 // 加载print函数
	sta v3
	lda.str "Hello World!!!"  // 加载Hello World!!!字符串
	sta v4
	builtin.tern3 v3, v4  // 调用print函数
	builtin.acc
}

运行Test262测试用例

运行前准备

1. 编译方舟运行时，编译命令：

./build.sh --product-name rk3568 --build-target ark_js_host_linux_tools_packages

2. 编译方舟前端，编译命令：

./build.sh --product-name rk3568 --build-target ets_frontend_build

说明：编译命令执行路径为项目根目录。

运行Test262

运行run_test262.py脚本，下载及运行Test262用例。

命令行格式：

python3 test262/run_test262.py [options]

执行路径为：项目根目录/arkcompiler/ets_frontend。

测试运行示例

• 运行ES51测试用例：

   python3 test262/run_test262.py --es51

• 仅运行ES2015测试用例：

   python3 test262/run_test262.py --es2015

• 仅运行ES2021测试用例：

   python3 test262/run_test262.py --es2021 only
  

• 运行ES2015和ES51和ES2021所有测试用例：

   python3 test262/run_test262.py --es2021 all

• 运行单一测试用例：

   python3 test262/run_test262.py --file test262/data/test_es5/language/statements/break/12.8-1.js

• 运行某目录下所有测试用例：

   python3 test262/run_test262.py --dir test262/data/test_es5/language/statements

• 使用`babel`把单个测试用例转换成es5后再运行：

   python3 test262/run_test262.py  --babel --file test262/data/test_es5/language/statements/break/12.8-1.js

测试输出

Test262所有用例的测试结果位于项目根目录/arkcompiler/ets_frontend/out下。shell中测试输出结果如下：

$python3 test262/run_test262.py --file test262/data/test_es2015/built-ins/Array/15.4.5.1-5-1.js

Wait a moment..........
Test command:
node
        test262/harness/bin/run.js
        --hostType=panda
        --hostPath=python3
        --hostArgs='-B test262/run_sunspider.py --ark-tool=/your_code_path/out/rk3568/clang_x64/arkcompiler/ets_runtime/ark_js_vm --ark-frontend-tool=/your_code_path/out/rk3568/clang_x64/arkcompiler/ets_frontend/build/src/index.js --libs-dir=/your_code_path/out/rk3568/clang_x64/global/i18n:/your_code_path/prebuilts/clang/ohos/linux-x86_64/llvm/lib:/your_code_path/out/rk3568/clang_x64/thirdparty/zlib/ --ark-frontend=ts2panda'
        --threads=15
        --mode=only strict mode
        --timeout=60000
        --tempDir=build/test262
        --test262Dir=test262/data
        --saveCompiledTests
        test262/data/test_es5/language/statements/break/12.8-1.js

PASS test262/data/test_es2015/built-ins/Array/15.4.5.1-5-1.js (strict mode)
Ran 1 tests
1 passed
0 failed
used time is: 0:01:04.439642

AOT执行

运行前准备

• 编译生成AOT编译器：

  ./build.sh --product-name rk3568  --build-target ets_frontend_build --build-target ark_js_host_linux_tools_packages --build-target arkcompiler/runtime_core:ark_host_linux_tools_packages

• 新建hello-world.ts文件，写入以下源码：

  declare function print(arg:any):string;
  print('Hello World!!!')

运行步骤

1. 通过方舟前端生成hello-world.abc文件，编译命令：

   /your_code_path/out/rk3568/clang_x64/arkcompiler/ets_frontend/es2abc --module --merge-abc hello-world.ts

2. 设置搜索路径：

   export LD_LIBRARY_PATH=/your_code_path/out/rk3568/clang_x64/arkcompiler/ets_runtime:/your_code_path/prebuilts/clang/ohos/linux-x86_64/llvm/lib:/your_code_path/out/rk3568/clang_x64/thirdparty/icu:/your_code_path/out/rk3568/clang_x64/thirdparty/zlib

3. 运行ark_js_vm，采集PGO信息，生成的PGO信息落盘在文件hello-world.ap：

   /your_code_path/out/rk3568/clang_x64/arkcompiler/ets_runtime/ark_js_vm --enable-pgo-profiler=true --compiler-pgo-profiler-path=hello-world.ap --entry-point=hello-world hello-world.abc

4. 通过AOT编译器生成an和ai文件，可以通过info日志观察到被编译的函数列表：

   /your_code_path/out/rk3568/clang_x64/arkcompiler/ets_runtime/ark_aot_compiler  --enable-pgo-profiler=true --compiler-pgo-profiler-path=hello-world.ap --log-level=info --aot-file=./hello-world hello-world.abc

5. 执行ark_js_vm：

   /your_code_path/out/rk3568/clang_x64/arkcompiler/ets_runtime/ark_js_vm --aot-file=./hello-world --entry-point=hello-world hello-world.abc

   执行结果如下：

   Hello World!!!

说明：此处“your_code_path”为源码目录路径。

工具链使用

方舟前端工具采用命令行交互方式，支持将ArkTS代码转换为方舟字节码，使其能够在方舟运行时上运行。支持Windows/Linux/Mac平台。

ArkTS字节码编译工具概述

使用前端工具将ArkTS文件转换为方舟字节码文件。方舟前端工具在linux平台上可通过全量编译或指定编译前端工具链获取。

构建编译：

$ ./build.sh --product-name rk3568 --build-target ets_frontend_build

$ cd out/rk3568/clang_x64/arkcompiler/ets_frontend/
$ ./es2abc [options] file.js

反汇编器工具概述

工具名称为ark_disasm，用于将二进制格式的方舟字节码文件转换为文本格式的方舟字节码文件。

编译生成反汇编工具：

./build.sh --product-name rk3568 --build-target arkcompiler/runtime_core:ark_host_linux_tools_packages

命令行格式：

ark_disasm [选项] 输入文件 输出文件

输入文件：二进制格式的方舟字节码

输出文件：文本格式的方舟字节码

AOT工具概述

AOT为Ahead Of Time的简称，也即提前编译，能够在Host端将字节码提前编译成Target端可运行的机器码，这样字节码可以获得充分编译优化，从而加速Target端的运行速度。

编译生成aot编译器：

./build.sh --product-name rk3568 --build-target ark_js_host_linux_tools_packages

命令行格式：

ark_aot_compiler [选项] 输入文件

输入文件：二进制格式的方舟字节码

输出文件：直接执行的机器码的an文件、存储序列化后ConstPool的ai文件（输出文件路径需使用--aot-file选项指定）

PGO工具概述

PGO为Profile-guided optimization的简称，也即配置文件引导的优化。该工具能够记录应用启动和性能场景中的高频（热点）函数，并将信息记录于对应的PGO Profiler文件。AOT编译器则可通过这些信息决策部分函数进行编译，从而在基本不影响应用运行性能的情况下，缩短编译时间，减少.an文件的大小。

编译生成aot编译器和ark js虚拟机

./build.sh --product-name rk3568 --build-target ark_js_host_linux_tools_packages

生成PGO Profiler文件

命令行格式：

ark_js_vm [选项] 输入文件

输入文件：二进制格式的方舟字节码

输出文件：保存有热点函数信息的ap文件

基于PGO Profiler的AOT编译

命令行格式：

ark_aot_compiler [选项] 输入文件

输入文件：二进制格式的方舟字节码，ap文件

输出文件：直接执行的机器码的an文件（基于pgo）