diff --git a/README.md b/README.md index 0c20735cf33dabfc7938412c420d3c535f437c74..99fc3c478191561e49881bf1067da31c7c9e361e 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,20 @@ # ARK JS Runtime Module -- [Directory Structure](#section161941989596) -- [Constraints](#section119744591305) -- [Build](#section137768191623) - - [Available APIs](#section175841548124517) - - [Usage Guidelines](#section129654513264) - -- [Repositories Involved](#section1371113476307) +- [ARK JS Runtime Module](#ark-js-runtime-module) + - [Introduction](#introduction) + - [Directory Structure](#directory-structure) + - [Constraints](#constraints) + - [Build](#build) + - [Available APIs](#available-apis) + - [Usage Guidelines](#usage-guidelines) + - [Repositories Involved](#repositories-involved) ### Introduction ARK JS Runtime is the runtime used by JavaScript \(JS\) applications on OpenHarmony. It consists of the JS object allocator, garbage collector \(GC\), a standard library compliant with ECMAScript specifications, ARK bytecode interpreter, inline caches that store hidden classes, and the ARK Foreign Function Interface \(AFFI\). +For more infomation, see: [ARK Runtime Subsystem](https://gitee.com/openharmony/docs/blob/master/en/readme/ARK-Runtime-Subsystem.md). + **ARK JS runtime architecture** ![](docs/figures/en-us_image_0000001149439242.png) @@ -49,7 +52,9 @@ ARK JS Runtime is the runtime used by JavaScript \(JS\) applications on OpenHarm ## Build +``` ./build.sh --product-name Hi3516DV300 --build-target ark\_js\_runtime +``` ### Available APIs @@ -60,20 +65,18 @@ For details, see [NAPI](https://gitee.com/openharmony/ace_napi/blob/master/READ For details about how to generate JS bytecodes, see [Using the Toolchain](docs/using-the-toolchain.md). To run bytecodes: - +``` cd out/release - LD\_LIBRARY\_PATH=clang\_x64/ark/ark\_js\_runtime:clang\_x64/ark/ark:clang\_x64/global/i18n:../../prebuilts/clang/ohos/linux-x86\_64/llvm/lib/ - ./clang\_x64/ark/ark\_js\_runtime/ark\_js\_vm helloworld.abc +``` -## Repositories Involved - -[ARK Runtime Subsystem](docs/ARK-Runtime-Subsystem.md) +For more infomation, please see: [ARK-Runtime-Usage-Guide](https://gitee.com/openharmony/ark_js_runtime/blob/master/docs/ARK-Runtime-Usage-Guide.md). -[ark/runtime\_core](https://gitee.com/openharmony/ark_runtime_core/blob/master/README.md) +## Repositories Involved -**[ark/js\_runtime](README.md)** +[ark\_runtime\_core](https://gitee.com/openharmony/ark_runtime_core) -[ark/ts2abc](https://gitee.com/openharmony/ark_ts2abc/blob/master/README.md) +**[ark\_js\_runtime](https://gitee.com/openharmony/ark_js_runtime)** +[ark\_ts2abc](https://gitee.com/openharmony/ark_ts2abc) diff --git a/README_zh.md b/README_zh.md index c492518f38125c7ec6a0ea96f1681d64490b1244..d7adae57ad981a1cb639d9666c14f950b526a1bc 100644 --- a/README_zh.md +++ b/README_zh.md @@ -1,17 +1,20 @@ # 方舟JS运行时组件 -- [目录](#section161941989596) -- [约束](#section119744591305) -- [编译构建](#section137768191623) - - [接口说明](#section175841548124517) - - [使用说明](#section129654513264) - -- [相关仓](#section1371113476307) +- [方舟JS运行时组件](#方舟js运行时组件) + - [简介](#简介) + - [目录](#目录) + - [约束](#约束) + - [编译构建](#编译构建) + - [接口说明](#接口说明) + - [使用说明](#使用说明) + - [相关仓](#相关仓) ### 简介 方舟JS运行时（ARK JavaScript Runtime）是OpenHarmony上JS应用使用的运行时。包含JS对象的分配器以及垃圾回收器（GC）、符合ECMAScript规范的标准库、用于运行ARK前端组件生成的方舟字节码（ARK Bytecode，abc）的解释器、用于存储隐藏类的内联缓存、方舟JS运行时对外的函数接口（AFFI）等模块。 +更多信息请参考：[方舟运行时子系统](https://gitee.com/openharmony/docs/blob/master/zh-cn/readme/ARK-Runtime-Subsystem-zh.md) + **方舟JS运行时组件架构图：** ![](docs/figures/zh-cn_image_0000001196712959.png) @@ -49,7 +52,9 @@ ## 编译构建 +``` ./build.sh --product-name Hi3516DV300 --build-target ark\_js\_runtime +``` ### 接口说明 @@ -59,21 +64,21 @@ NAPI接口说明参考[NAPI组件](https://gitee.com/openharmony/ace_napi/blob/m JS生成字节码参考[工具链使用](docs/using-the-toolchain-zh.md) -字节码执行 - +字节码执行： +``` cd out/release LD\_LIBRARY\_PATH=clang\_x64/ark/ark\_js\_runtime:clang\_x64/ark/ark:clang\_x64/global/i18n:../../prebuilts/clang/ohos/linux-x86\_64/llvm/lib/ ./clang\_x64/ark/ark\_js\_runtime/ark\_js\_vm helloworld.abc +``` -## 相关仓 - -[方舟运行时子系统](docs/ARK-Runtime-Subsystem-zh.md) +更多使用说明请参考：[方舟运行时使用指南](https://gitee.com/openharmony/ark_js_runtime/blob/master/docs/ARK-Runtime-Usage-Guide-zh.md) -[ark/runtime\_core](https://gitee.com/openharmony/ark_runtime_core/blob/master/README_zh.md) +## 相关仓 -**[ark/js\_runtime](README_zh.md)** +[ark\_runtime\_core](https://gitee.com/openharmony/ark_runtime_core) -[ark/ts2abc](https://gitee.com/openharmony/ark_ts2abc/blob/master/README_zh.md) +**[ark\_js\_runtime](https://gitee.com/openharmony/ark_js_runtime)** +[ark\_ts2abc](https://gitee.com/openharmony/ark_ts2abc) diff --git a/docs/ARK-Runtime-Subsystem-zh.md b/docs/ARK-Runtime-Subsystem-zh.md deleted file mode 100644 index 12a2a46efaaa65bb9f77afb48c293fb3a5c383b1..0000000000000000000000000000000000000000 --- a/docs/ARK-Runtime-Subsystem-zh.md +++ /dev/null @@ -1,67 +0,0 @@ -# 方舟运行时子系统 - -- [简介](#section11660541593) -- [目录](#section161941989596) -- [说明](#section18393638195820) -- [相关仓](#section1371113476307) - -## 简介 - -方舟\(ARK\)是华为自研的统一编程平台，包含编译器、工具链、运行时等关键部件，支持高级语言在多种芯片平台的编译与运行，并支撑OpenHarmony操作系统及其应用和服务运行在手机、个人电脑、平板、电视、汽车和智能穿戴等多种设备上的需求。本次开源的ARK-JS提供的能力是在OpenHarmony操作系统中编译和运行JavaScript语言\(本文后面简称JS\)。 - -本次开源的ARK-JS分成两个部分，分别是JS编译工具链与JS运行时。JS工具链将JS源码编译成方舟字节码\(ARK Bytecode\)，JS运行时负责执行生成的方舟字节码\(后续如无特殊说明，字节码特指方舟字节码\)。 - -JS编译工具链架构： - -![](figures/zh-cn_image_0000001197967983.png) - -js前端编译器，将JavaScript源码解析为AST后，经过AST变换、字节码生成器、寄存器分配后由native emiter产生方舟字节码文件\(abc文件\) - -JS运行时（Runtime）架构： - -![](figures/zh-cn_image_0000001197275269.png) - -ARK-JS Runtime以方舟字节码文件作为输入并直接运行字节码文件，实现对应的JS语义逻辑。 - -ARK-JS Runtime主要由四个部分组成： - -- Core Runtime - - Core Runtime主要由语言无关的基础运行库组成，包括承载字节码的ARK File组件、支持Debugger的Tooling组件、负责对应系统调用的ARK Base组件等。 - -- Execution Engine - - 执行引擎目前包含执行字节码的解释器、缓存隐藏类和内联缓存、以及剖析记录运行时类型的Profiler。 - -- ECMAScript Runtime - - ECMAScript Runtime则包含了各种JS对象的分配器、垃圾回收器、以及用以支撑ECMAScript规范的内部运行库。 - -- AFFI \(ARK Foreign Function Interface\) - - AFFI是ARK JS运行时的C++语言外部函数接口。 - - -## 目录 - -``` -/ark -├── js_runtime # JS运行时组件 -├── runtime_core # 运行时公共组件 -└── ts2abc # 方舟编译器中JavaScript语言的前端工具 -``` - -## 说明 - -见各组件说明 - -## 相关仓 - -**[方舟运行时子系统](ARK-Runtime-Subsystem-zh.md)** - -[ark/runtime\_core](https://gitee.com/openharmony/ark_runtime_core/blob/master/README_zh.md) - -[ark/js\_runtime](https://gitee.com/openharmony/ark_js_runtime/blob/master/README_zh.md) - -[ark/ts2abc](https://gitee.com/openharmony/ark_ts2abc/blob/master/README_zh.md) - diff --git a/docs/ARK-Runtime-Subsystem.md b/docs/ARK-Runtime-Subsystem.md deleted file mode 100644 index 58a909c181d610245a8e769356baff8eeeadabad..0000000000000000000000000000000000000000 --- a/docs/ARK-Runtime-Subsystem.md +++ /dev/null @@ -1,67 +0,0 @@ -# ARK Runtime Subsystem - -- [Introduction](#section11660541593) -- [Directory Structure](#section161941989596) -- [Note](#section18393638195820) -- [Repositories Involved](#section1371113476307) - -## Introduction - -ARK is a unified programming platform developed by Huawei. Its key components include a compiler, toolchain, and runtime. ARK supports compilation and running of high-level programming languages on the multi-chip platform and accelerates the running of the OpenHarmony operating system and its applications and services on mobile phones, PCs, tablets, TVs, automobiles, and smart wearables. The ARK-JS open sourced this time provides the capability of compiling and running the JavaScript \(JS\) language on the OpenHarmony operating system. - -The ARK-JS consists of two parts: JS compiler toolchain and JS runtime. The JS compiler toolchain compiles JS source code into ARK bytecodes. The JS runtime executes the generated ARK bytecodes. Unless otherwise specified, bytecodes refer to ARK bytecodes in this document. - -The following figure shows the architecture of the JS compiler toolchain. - -![](figures/en-us_image_0000001197967983.png) - -The JS front-end compiler parses the JS source code into an abstract syntax tree \(AST\), which is processed by the AST transformer, bytecode generator, and register allocator. The native emiter generates the ARK bytecode file \(.abc\). - -The following figure shows the JS runtime architecture. - -![](figures/en-us_image_0000001197275269.png) - -ARK-JS Runtime runs ARK bytecode files to implement JS semantic logic. - -ARK-JS Runtime consists of the following: - -- Core Runtime - - Core Runtime consists of basic language-irrelevant runtime libraries, including ARK File, Tooling, and ARK Base. ARK File provides bytecodes. Tooling supports Debugger. ARK Base is responsible for implementing system calls. - -- Execution Engine - - The Execution Engine consists of an interpreter that executes bytecodes, Inline Caches that store hidden classes, and Profiler that analyzes and records runtime types. - -- ECMAScript Runtime - - ECMAScript Runtime consists of the JS object allocator, garbage collector \(GC\), and an internal library that supports ECMAScript specifications. - -- ARK Foreign Function Interface \(AFFI\) - - The AFFI provides a C++ function interface for ARK-JS runtime. - - -## Directory Structure - -``` -/ark -├── js_runtime # JS runtime module -├── runtime_core # Runtime common module -└── ts2abc # JS front-end tool of ARK compiler -``` - -## Note - -For details, see the note of each module. - -## Repositories Involved - -**[ARK Runtime Subsystem](ark-runtime-subsystem.md)** - -[ark/runtime\_core](https://gitee.com/openharmony/ark_runtime_core/blob/master/README.md) - -[ark/js\_runtime](https://gitee.com/openharmony/ark_js_runtime/blob/master/README.md) - -[ark/ts2abc](https://gitee.com/openharmony/ark_ts2abc/blob/master/README.md) - diff --git a/docs/ARK-Runtime-Usage-Guide-zh.md b/docs/ARK-Runtime-Usage-Guide-zh.md index efb910bbd6c01f32bc668f59b08b1bdcb358fb42..a3216281e137e8cd645f590566cc1240d0a73fd9 100644 --- a/docs/ARK-Runtime-Usage-Guide-zh.md +++ b/docs/ARK-Runtime-Usage-Guide-zh.md @@ -1,6 +1,6 @@ # 方舟运行时使用指南 -- [综述](overview-zh.md) +- [概述](overview-zh.md) - [环境搭建和编译](environment-setup-and-compilation-zh.md) - [开发实例](development-example-zh.md) - [工具链使用](using-the-toolchain-zh.md) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000000000000000000000000000000000..4ee1d8459181ab7742070f847750bdbb413d0ded --- /dev/null +++ b/docs/README.md @@ -0,0 +1,7 @@ +# ARK Runtime Usage Guide + +- [Overview](overview.md) +- [Environment Setup and Compilation](environment-setup-and-compilation.md) +- [Development Example](development-example.md) +- [Using the Toolchain](using-the-toolchain.md) + diff --git a/docs/README_zh.md b/docs/README_zh.md new file mode 100644 index 0000000000000000000000000000000000000000..a3216281e137e8cd645f590566cc1240d0a73fd9 --- /dev/null +++ b/docs/README_zh.md @@ -0,0 +1,7 @@ +# 方舟运行时使用指南 + +- [概述](overview-zh.md) +- [环境搭建和编译](environment-setup-and-compilation-zh.md) +- [开发实例](development-example-zh.md) +- [工具链使用](using-the-toolchain-zh.md) + diff --git a/docs/development-example-zh.md b/docs/development-example-zh.md index 6527605b79e9760c36ebbd205f2c0ebf1084f22b..b1c7e74e2bfcc35821283f2f21c849b419283772 100644 --- a/docs/development-example-zh.md +++ b/docs/development-example-zh.md @@ -1,13 +1,21 @@ # 开发实例 -- [HelloWorld](#section105987593810) -- [运行Test262测试用例](#section118471435115815) +- [开发实例](#开发实例) + - [HelloWorld](#helloworld) + - [运行前准备](#运行前准备) + - [运行hello-world.js](#运行hello-worldjs) + - [反汇编hello-world.abc](#反汇编hello-worldabc) + - [运行Test262测试用例](#运行test262测试用例) + - [运行前准备](#运行前准备-1) + - [运行Test262](#运行test262) + - [测试运行示例](#测试运行示例) + - [测试输出](#测试输出) 本章节将介绍基于方舟运行时的开发测试实例。 ## HelloWorld -运行前准备 +### 运行前准备 1. 编译方舟运行时，编译命令： @@ -15,15 +23,15 @@ ./build.sh --product-name Hi3516DV300 --build-target ark_js_runtime ``` -1. 编译方舟前端，编译命令： +2. 编译方舟前端，编译命令： ``` ./build.sh --product-name Hi3516DV300 --build-target ark_ts2abc_build ``` -_注：编译命令执行路径为项目根目录。_ +**说明**：编译命令执行路径为项目根目录。 -运行hello-world.js +### 运行hello-world.js 新建hello-world.js文件，写入以下源码： @@ -60,10 +68,9 @@ _注：编译命令执行路径为项目根目录。_ ->![](public_sys-resources/icon-note.gif) **说明：** ->此处“_your code path_”为源码目录路径。 +**说明**：此处“_your code path_”为源码目录路径。 -反汇编hello-world.abc +### 反汇编hello-world.abc 执行如下命令，结果输出到output文件中： @@ -110,7 +117,7 @@ hello-world.abc反汇编结果如下： ## 运行Test262测试用例 -运行前准备 +### 运行前准备 1. 编译方舟运行时，编译命令： @@ -124,9 +131,9 @@ hello-world.abc反汇编结果如下： ./build.sh --product-name Hi3516DV300 --build-target ark_ts2abc_build ``` -_注：编译命令执行路径为项目根目录。_ +**说明**：编译命令执行路径为项目根目录。 -运行Test262 +### 运行Test262 运行run\_test262.py脚本，下载及运行Test262用例。 @@ -228,7 +235,7 @@ python3 test262/run_test262.py [options] -测试运行示例 +### 测试运行示例 - 运行ES51测试用例： @@ -268,7 +275,7 @@ python3 test262/run_test262.py [options] ``` -测试输出 +### 测试输出 Test262所有用例的测试结果位于项目根目录/ark/ts2abc/out下。shell中测试输出结果如下： diff --git a/docs/development-example.md b/docs/development-example.md index 242f2a735ddaaa4ec7053b706f90a6eeec278c6b..0aaec3aab387885da5360faa675af2b525590a2c 100644 --- a/docs/development-example.md +++ b/docs/development-example.md @@ -7,7 +7,7 @@ This section describes how to develop and test ARK runtime. ## HelloWorld -Preparations +### Preparations 1. Run the following command to compile ARK runtime: @@ -15,15 +15,15 @@ Preparations ./build.sh --product-name Hi3516DV300 --build-target ark_js_runtime ``` -1. Run the following command to compile the ARK frontend: +2. Run the following command to compile the ARK frontend: ``` ./build.sh --product-name Hi3516DV300 --build-target ark_ts2abc_build ``` -Note: Run the compilation commands in the project root directory. +**NOTE**: Run the compilation commands in the project root directory. -Running **hello-world.js** +### Running **hello-world.js** Create the **hello-world.js** file and write the following source code into the file: @@ -58,12 +58,9 @@ Run the **hello-world.js** file. Hello World!!! ``` +**NOTE**: In the preceding command, _your code path_ indicates the source code directory. - ->![](public_sys-resources/icon-note.gif) **NOTE:** ->In the preceding command, _your code path_ indicates the source code directory. - -Disassembling **hello-world.abc** +### Disassembling **hello-world.abc** Run the following command to export the result to the **output** file: @@ -110,7 +107,7 @@ The output is as follows: ## Performing Test Case Test262 -Preparations +### Preparations 1. Run the following command to compile ARK runtime: @@ -118,15 +115,15 @@ Preparations ./build.sh --product-name Hi3516DV300 --build-target ark_js_runtime ``` -1. Run the following command to compile the ARK frontend: +2. Run the following command to compile the ARK frontend: ``` ./build.sh --product-name Hi3516DV300 --build-target ark_ts2abc_build ``` -Note: Run the compilation commands in the project root directory. +**NOTE**: Run the compilation commands in the project root directory. -Running Test262 +### Running Test262 Run the **run\_test262.py** script to download and run the Test262 test case. @@ -231,7 +228,7 @@ Run the script in _Project root directory_**/ark/ts2abc**. -Example +### Example - Run test case ES51. @@ -271,7 +268,7 @@ Example ``` -Test Output +### Test Output The results of all Test262 test cases are available in the **_Project root directory_/ark/ts2abc/out**. The test result in the shell is as follows: diff --git a/docs/figures/en-us_image_0000001197275269.png b/docs/figures/en-us_image_0000001197275269.png deleted file mode 100644 index 2f78e5f3e10a2b99c60ca31dc0f23ae5fb89f7a6..0000000000000000000000000000000000000000 Binary files a/docs/figures/en-us_image_0000001197275269.png and /dev/null differ diff --git a/docs/figures/en-us_image_0000001197967983.png b/docs/figures/en-us_image_0000001197967983.png deleted file mode 100644 index e8e9951f3f2dc5b566a3d9b36229def46c41aecd..0000000000000000000000000000000000000000 Binary files a/docs/figures/en-us_image_0000001197967983.png and /dev/null differ diff --git a/docs/figures/zh-cn_image_0000001197275269.png b/docs/figures/zh-cn_image_0000001197275269.png deleted file mode 100644 index 2f78e5f3e10a2b99c60ca31dc0f23ae5fb89f7a6..0000000000000000000000000000000000000000 Binary files a/docs/figures/zh-cn_image_0000001197275269.png and /dev/null differ diff --git a/docs/figures/zh-cn_image_0000001197967983.png b/docs/figures/zh-cn_image_0000001197967983.png deleted file mode 100644 index e8e9951f3f2dc5b566a3d9b36229def46c41aecd..0000000000000000000000000000000000000000 Binary files a/docs/figures/zh-cn_image_0000001197967983.png and /dev/null differ diff --git a/docs/overview-zh.md b/docs/overview-zh.md index f324f3d9304de9ac6bdd2ea5776022d15181be6a..d3d4487ce18dc69a2a33ccfb8120f452ab0f1b62 100644 --- a/docs/overview-zh.md +++ b/docs/overview-zh.md @@ -1,4 +1,4 @@ -# 综述 +# 概述 方舟\(ARK\)是华为自研的统一编程平台，包含编译器、工具链、运行时等关键部件，支持高级语言在多种芯片平台的编译与运行，并支撑OpenHarmony标准操作系统及其应用和服务运行在手机、个人电脑、平板、电视、汽车和智能穿戴等多种设备上的需求。本次开源的ARK-JS提供的能力是在OpenHarmony操作系统中编译和运行JavaScript语言\(本文后面简称JS\)。 diff --git a/docs/using-the-toolchain-zh.md b/docs/using-the-toolchain-zh.md index 44b7dd46ae07fb5b041fb66d5796cf3a679deaac..9fee49691ad4e55f7f3b059b69445fb556c0ed5c 100644 --- a/docs/using-the-toolchain-zh.md +++ b/docs/using-the-toolchain-zh.md @@ -2,7 +2,7 @@ 方舟前端工具采用命令行交互方式，支持将JS代码转换为方舟字节码，使其能够在方舟运行时上运行。支持Windows/Linux/Mac平台。 -JS字节码编译工具概述 +## JS字节码编译工具概述 将JS文件转换为方舟字节码。 @@ -137,7 +137,7 @@ node --expose-gc index.js [选项] file.js -汇编器工具概述 +## 汇编器工具概述 工具名称为ark\_asm，用于将文本格式的方舟字节码文件转换为二进制格式的方舟字节码文件。 @@ -191,7 +191,7 @@ ark_asm [选项] 输入文件 输出文件 输出文件：二进制格式的方舟字节码 -反汇编器工具概述 +## 反汇编器工具概述 工具名称为ark\_disasm，用于将二进制格式的方舟字节码文件转换为文本格式的方舟字节码文件。 diff --git a/docs/using-the-toolchain.md b/docs/using-the-toolchain.md index 95446f2227e3e431343a26ea6e25725e3be8a062..9d00fa90b1230c914f5fc297dcbbc9ad877f18ef 100644 --- a/docs/using-the-toolchain.md +++ b/docs/using-the-toolchain.md @@ -2,7 +2,7 @@ The ARK front-end tools use the command line interaction mode and convert JS code into ARK bytecodes that can run on ARK runtime. The toolchain supports Windows, Linux, and macOS. -JS Bytecode Compiler +## JS Bytecode Compiler Converts a JS file into ARK bytecodes. @@ -137,7 +137,7 @@ node --expose-gc index.js [option] file.js -Assembler ark\_asm +## Assembler ark\_asm The ark\_asm assembler converts the text ARK bytecode file into a bytecode file in binary format. @@ -191,7 +191,7 @@ Input file: ARK bytecodes in text format Output file: ARK bytecodes in binary format -Disassembler ark\_disasm +## Disassembler ark\_disasm The ark\_disasm disassembler converts binary ARK bytecodes into readable text ARK bytecodes.