ArkCompiler Runtime Usage Guide

Introduction

ArkCompiler is a unified compilation and runtime platform that supports joint compilation and running across programming languages and chip platforms.

• ArkCompiler consists of two parts: compiler toolchain and runtime.
• ArkCompiler eTS Runtime consists of four subsystems: Core Subsystem, Execution Subsystem, Compiler Subsystem, and Runtime Subsystem.
• ArkCompiler features: support for native types, concurrency model optimization, concurrency API, and security.

For details about the VM design, see Overview.

Environment Setup and Compilation

Environment Configuration

Setting Up the Ubuntu Environment

• Installing initial environment software (Ubuntu 18.04 or 20.04 is recommended)

  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
  

Source Code Acquisition

For details about how to download the source code, see Obtaining Source Code.

Code Compilation

Note: The following commands must be executed in the root directory of the source code.

1. First compilation:

   ./build.sh --product-name rk3568
   

2. Compile an Ark eTS runtime after the first compilation.

   Compile for the linux-x86 architecture.

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

   Compile for the oh-arm64 architecture.

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

   Compile for the oh-arm32 architecture.

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

3. Compile the Ark eTS frontend after the first compilation.

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

   For more compilation commands, see ArkCompiler Development.

Note: The preceding compilation commands are for the release version. To compile the debug version, add the compilation option --gn-args is_debug=true.

The binary files related to ARK are available in the following paths:

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

Development Example

The following describes how to develop and test Ark eTS runtime.

HelloWorld

Preparations

• Compile the Ark eTS runtime and Ark eTS frontend.

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

Running hello-world.js

Create the hello-world.js file and write the following source code into the file:

print("Hello World!!!");

Procedure:

1. Use the Ark eTS frontend to create the hello-world.abc file.

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

2. Run the hello-world.abc file.

   1. Set the search path.

      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. Run ark_js_vm.

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

      The execution result is as follows:

      Hello World!!!
      

Note: your_code_path indicates the source code directory.

Disassembling hello-world.abc

Compile and generate the disassembler tool.

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

Run the following command to export the result to the output.pa file:

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

The output is as follows:

#
# 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 // Load the print function.
	sta v3
	lda.str "Hello World!!!"  // Load the Hello World!!! string.
	sta v4
	builtin.tern3 v3, v4  // Call the print function.
	builtin.acc
}

Performing Test Case Test262

Preparations

1. Run the following command to compile the Ark eTS runtime:

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

2. Run the following command to compile the Ark eTS frontend:

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

Note: The compilation command is executed in the project root directory.

Running Test262

Run the run_test262.py script to download and run the Test262 test case.

Command:

python3 test262/run_test262.py [options]

The execution path is project root directory/arkcompiler/ets_frontend.

Option	Description
--h, --help	Displays help information.
--dir DIR	Specifies the directory to be tested.
--file FILE	Specifies the file to be tested.
--mode [{1, 2, 3}]	Specifies the mode. **1**: Default mode only; **2**: Strict mode only; **3**: Default mode and strict mode.
--es51	Runs the Test262 ES5.1 version.
--es2015 [{all, only}]	Runs the Test262 ES2015 version. **all**: includes all test cases. **only**: includes only ES2015.
--esnext	Runs the Test262-ES.next version.
--engine FILE	Runs other engines for testing. You can specify the binary file (such as d8, hermes, jsc, and qjs).
--babel	Sets whether to enable Babel conversion.
--timeout TIMEOUT	Sets the test timeout time (in millisecond).
--threads THREADS	Sets the number of concurrent running threads.
--hostArgs HOSTARGS	Passes command parameters to eHost.
--ark-tool ARK_TOOL	Specifies the binary tool of Ark eTS runtime.
--ark-frontend-tool ARK_FRONTEND_TOOL	Specifies the conversion tool of Ark eTS frontend.
--libs-dir LIBS_DIR	Specifies the path set of the dependency .so files. Use colons to separate multiple paths.
--ark-frontend [{ts2panda, es2panda}]	Specifies the frontend.

Example

• Run test case ES51.

   python3 test262/run_test262.py --es51
  

• Run test case ES2015 only.

   python3 test262/run_test262.py --es2015
  

• Run test case ES2021 only.

   python3 test262/run_test262.py --es2021 only
  
  

• Run all ES2015, ES51, and ES2021 test cases.

   python3 test262/run_test262.py --es2021 all
  

• Run a test case.

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

• Run all test cases in a directory.

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

• Use `Babel` to convert a test case into ES5 and then run the test case.

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

Test Output

The results of all Test262 test cases are available in the Project root directory/arkcompiler/ets_frontend/out. The test result in the shell is as follows:

$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 Execution

Preparations

• Compile and generate the AOT compiler.

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

• Create the hello-world.ts file and write the following source code into the file:

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

Procedure

1. Use the Ark eTS frontend to create the hello-world.abc file.

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

2. Set the search path.

   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. Run ark_js_vm to collect PGO information. The generated PGO information is stored in the hello-world.ap file.

   /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. Generate .an and .ai files using the AOT compiler. You can view the list of compiled functions in the info log.

   /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. Run 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
   

   The execution result is as follows:

   Hello World!!!
   

Note: your_code_path indicates the source code directory.

Using the Toolchain

The Ark eTS frontend tools use the command line interaction mode and convert ArkTS code into Ark bytecode that can run on Ark eTS runtime. The toolchain supports Windows, Linux, and macOS.

ArkTS Bytecode Compiler

Use the frontend tool to convert ArkTS files into Ark bytecode files. On Linux, you can obtain the Ark eTS frontend toolchain through full compilation or by specifying specific compilation.

Build commands:

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

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

Option	Description	Value Range	Default Value
--debug-info	Includes debug information.	-	-
--debugger-evaluate-expression	Evaluates base64-encoded expressions in debugger.	-	-
--dump-assembly	Outputs an assembly file.	-	-
--dump-ast	Prints the parsed abstract syntax tree (AST).	-	-
--dump-debug-info	Prints debug information.	-	-
--dump-literal-buffer	Prints the content of the literal buffer.	-	-
--dump-size-stat	Displays bytecode statistics.	-	-
--extension	Specifies the input type.	['js', 'ts', 'as']	-
--help	Displays help information.	-	-
--module	Compile in ESM mode.	-	-
--opt-level	Specifies the compilation optimization level.	['0', '1', '2']	0
--output	Specifies the output file path.	-	-
--parse-only	Parses only the input file.	-	-
--thread	Specifies the number of threads used for generating bytecode.	0 to the maximum number of threads supported by the machine	0

Disassembler Tool

The ark_disasm disassembler converts binary Ark bytecode files into text Ark bytecode files.

Compile and generate the disassembler tool.

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

Command:

ark_disasm [Option] Input file Output file

Option	Description
--debug	Enables the debug information. If **--debug-file** is not specified, the information is output in standard output mode. The default value is **false**.
--debug-file	Specifies the path of the debug information output file. The default value is **std::cout**.
--skip-string-literals	Replaces the string with the corresponding **string_ID**, which can reduce the size of the output file. The default value is **false**.
--quiet	Opens all **--skip-*** options. The default value is **false**.
--help	Displays help information.
--verbose	Outputs more information about classes and methods in the file. The default value is **false**.

Input file: Ark bytecode in binary format

Output file: Ark bytecode in text format

AOT Tool

Ahead Of Time (AOT) compilation is a process of compiling bytecode into machine code that can be executed on the target device in advance on the host. In this way, the bytecode can be fully compiled and optimized, accelerating the running speed of the target device.

Compile and generate the AOT compiler.

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

Command:

ark_aot_compiler [Option] Input file

Option	Description
--aot-file	Specifies the path of the AOT output file (without the file name extension). Default value: aot_file.
--compiler-opt-type-lowering	Generates machine code with a higher optimization level using type information. Default value: true.
--compiler-opt-max-method	Sets the method size threshold for AOT compilation. If the method size exceeds the threshold, the method is not compiled. Default value: 32 KB.
--compiler-opt-level	Sets the optimization level of AOT. Default value: 3.
--compiler-log	Prints the log information of AOT, such as IR graphs and assembly code. Default value: none.
--compiler-log-snapshot	Prints the log information related to serialization. Default value: false.
--compiler-log-time	Prints the time consumption of each optimization pass during AOT compilation. Default value: false.

Input file: Ark bytecode in binary format

Output file: .an file of the machine code that can be directly executed or .ai file of the serialized ConstPool (The output file path must be specified using the --aot-file option.)

PGO Tool

Profile-Guided Optimization (PGO) records frequently used (hotspot) functions in application startup and performance scenarios and stores the information in the corresponding PGO Profiler file. The AOT compiler can use the information to determine whether to compile some functions. In this way, the compilation time is shortened and the size of the .an file is reduced without affecting the application running performance.

Compile and generate the AOT compiler and Ark JS VM.

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

Generating a PGO Profiler File

Command:

ark_js_vm [Option] Input file

Option	Description
--enable-pgo-profiler	Enables the PGO tool. Default value: false.
--compiler-pgo-profiler-path	Specifies the path for storing the PGO Profiler file. Default value: none.
--compiler-pgo-hotness-threshold	Specifies the threshold for hotspot functions. If the number of function calls is greater than the threshold, the function is considered as a hotspot function. Default value: 2.

Input file: Ark bytecode in binary format

Output file: .ap file that stores hotspot function information

AOT Compilation Based on the PGO Profiler

Command:

ark_aot_compiler [Option] Input file

Option	Description
--compiler-pgo-profiler-path	Specifies the path of the PGO Profiler file. Default value: none.
--compiler-pgo-hotness-threshold	Specifies the threshold of the number of function calls for enabling PGO compilation. Only the functions whose number of calls recorded in the profile file is greater than the threshold are compiled. Default value: 2.

Input file: .ap file that contains Ark bytecode in binary format

Output file: .an file that contains the machine code for direct execution (based on PGO)