1
2# The cheat sheet for ArkTS frontend
3
4### How to compile a module
5
6At the beginning, need to define what we want to compile.
7There are three kinds of compilation units:
8
9- *Separate modules*
10- *Declaration modules*
11- *Packages*
12
13(For more information, see ArkTS spec 13 chapter)
14In any case, regardless of whether we have an entry point or not, the compilation
15and execution commands will be the same and look like this:
16
17```bash
18# compilation of separate module and library
19./bin/es2panda --extension=sts --output=out.abc --opt-level=2 x.sts
20./bin/es2panda --extension=sts --output=etsstdlib.abc --opt-level=2 --gen-stdlib=true
21# execution command
22./bin/ark --boot-panda-files=etsstdlib.abc --load-runtimes=ets out.abc ETSGLOBAL::main
23```
24
25More details about separate modules, conceptually:
26- A separate module can have an entry point (be a program) or be a module with no entry point
27which can be imported and used as a kind of library
28- If a module has an entry point then
29
30```
31Entry_point := ArkTS_main | ArkTS_top-level-statements | ArkTS_top-level-statements ArkTS_main - 3 options
32Thus, Runtime_main () {
33  if (ArkTS_top_level_statements_in_place) call ArkTS_top-level-statements  // 1st step
34  if (ArkTS_main_in_place) call ArkTS_main                                  // 2nd step
35} // Case, when both are missed, should never happen - guaranteed by front-end and code generation
36```
37
38In practice:
39For the 1st step all top-level statements (see spec 13.8 point) will be placed inside
40*ETSGLOBAL._$init$_()* function which is called inside *ETSGLOBAL._cctor_()*.
41For the 2nd step we just always generate *ETSGLOBAL.main()* function and call after
42constructor for ETSGLOBAL. But also *ETSGLOBAL._$init$_()* can be called as a consequence of `main` call.
43
44*Note1:* `main` entrypoint method is possibly synthetic and always exists actually.
45*Note2:* Package modules are not fully supported, see #16267 internal issue.
46
47### How to execute a module
48
49The process of program execution on our VM is the same in all cases.
50To execute compiled module *out.abc* we have several options:
51
52```bash
53# Interpreter
54./bin/ark --compiler-enable-jit=false --boot-panda-files=etsstdlib.abc \
55--load-runtimes=ets out.abc ETSGLOBAL::main
56
57# JIT
58./bin/ark --compiler-enable-jit=true --boot-panda-files=etsstdlib.abc \
59 --load-runtimes=ets out.abc ETSGLOBAL::main
60
61# AOT - 2 steps
62./bin/ark_aot --boot-panda-files=etsstdlib.abc --load-runtimes=ets \
63--paoc-panda-files out.abc --paoc-output out.aot
64./bin/ark --boot-panda-files=etsstdlib.abc --load-runtimes=ets \
65--aot-files=out.aot out.abc ETSGLOBAL::main
66```
67
68Some additional options that can be helpful:
69- *--no-async-jit*
70- *--compiler-hotness-threshold=0* (to initiate jit compilation on the first method call)
71For more details see *./bin/ark --help*.
72
73### How to compile a library module
74
75The library module is compiled the same way as a regular module:
76
77```bash
78./bin/es2panda --extension=sts --output=out.abc --opt-level=2 --gen-stdlib=false /path/to/module/folder
79```
80
81*Notes:*
82- Standard library is an implicit import as defined in spec 13.5 point.
83As for now it's imported via *arktsconfig.json* file. This file is generated by cmake in the
84*path/to/build/tools/es2panda/generated/* folder. It has 2 default paths related to stdlib -
85*std* and *compat*. They're imported in each module that we compile.
86- Package modules are not fully supported, see #16267 internal issue.
87
88### How to use .abc and .d.sts without samples
89
90todo
91
92### How to find out what is in .abc
93
94To see what entities were generated by es2panda, we have *ark_disasm* tool.
95Its input is .abc file, its output is .pa (panda assembler) file.
96
97```bash
98./bin/ark_disasm out.abc out.pa
99```
100
101It shows all functions, instructions, records, also their flags, access modifiers
102and external/internal marks.
103
104### How package names are involved in the program
105
106Package names become a prefix of all entities declared in a package. For example,
107if we have such code:
108
109```typescript
110package P1
111function foo() {}
112```
113
114The foo name in the bytecode will be *P1.ETSGLOBAL.foo*.
115*Note:* For now we have some problems with generating names for packages
116
117### About —global-module-prefix option
118
119todo
120
121### How does global scope affect .abc
122
123todo
124
125### What is available without importing
126
127Implicit import is defined in spec 13.5 point. In details, we have *arktsconfig.json*
128file. This file is generated by cmake in the *path/to/build/tools/es2panda/generated/*
129folder. It has 2 default paths related to stdlib - *std* and *compat*. They're imported
130in each module that we compile. The default config file looks like this:
131
132```json
133{
134  "compilerOptions": {
135    "baseUrl": "/path/to/static_core",
136    "paths": {
137      "std": ["/path/to/static_core/plugins/ets/stdlib/std"],
138      "escompat": ["/path/to/static_core/plugins/ets/stdlib/escompat"],
139      "import_tests": ["/path/to/static_core/tools/es2panda/test/parser/ets/import_tests"],
140      "dynamic_import_tests": ["/path/to/static_core/tools/es2panda/test/parser/ets/dynamic_import_tests"]
141    },
142    "dynamicPaths": {
143      "dynamic_js_import_tests": {"language": "js", "hasDecl": false},
144      "/path/to/static_core/tools/es2panda/test/parser/ets/dynamic_import_tests": {"language": "js", "hasDecl": true}
145    }
146  }
147}
148```
149
150In additional, implicitly imported paths can be added. After that, your custom config file
151should be passed to the appropriate option:
152
153```bash
154./bin/es2panda --extension=sts --output=out.abc --opt-level=2 --gen-stdlib=false \
155--arktsconfig=/path/to/arktsconfig.json x.sts
156```
157
158### How to make one .abc file from two
159
160Tool *ark_link* can do it. Need to pass an arbitrary number of files as arguments to
161this application and it will output a combined .abc file.
162
163```bash
164./bin/ark_link --output out.abc -- a.abc b.abc
165```
166
167*Note:* Be aware of redefinition.
168
169### How to connect the native .so
170
171Have 2 options to form a correct .so for further work with it:
172- Need to register all the functions that will be called from ts on the native side.
173How to do this - see the file peer_lib/cpp/arkts/convertors-ark.cc/convertors-ark.cc
174from the https://gitee.com/nikolay-igotti/idlize/ repo
175- Register through the construction:
176"ETS_EXPORT ets_"return type" ETS_CALL ETS_classname_methodname(EtsEnv *, args) {..}",
177e.g.:
178
179```cpp
180extern "C" ETS_EXPORT ets_int ETS_CALL EtsNapiOnLoad(EtsEnv *env) {
181    if (!registerNatives(env, env->FindClass("NativeModule.NativeModule"))) return -1;
182        return ETS_NAPI_VERSION_1_0;
183}
184```
185
186### How to execute program with native .so
187
188Need to write *loadLibrary("name of the .so")* in the right place on the ts side.
189An example can be found in *NativeModule.sts* file which can be generated by:
190
191```bash
192npm panda:sdk:install
193arkts:make
194```
195
196Finally, need to execute with LD_LIBRARY_PATH=/path/to/directory/with/so passed to ark,
197so that the code that loads the lib will see it.
198
199### How to connect interop with dynamic js vm
200
201todo
202
203### What are the limits of the internal keyword? One .abc? One module?
204
205todo
206