• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Configuring arkOptions in build-profile.json5
2
3## Overview
4
5**arkOptions** is used to configure settings related to ArkTS compilation. This topic describes the configuration of the **types**, **maxFlowDepth**, and **transformLib** options in **arkOptions**. For more settings, see [build-profile.json5](https://developer.huawei.com/consumer/en/doc/harmonyos-guides/ide-hvigor-configuration-file-overview).
6
7## types
8
9### Description
10
11  Field **types** in **arkOptions**
12
13| Name| Description| Configuration Scope| Data Type| Optional|
14| -------- | -------- | -------- | -------- | -------- |
15| types | Specifies type declaration files to be globally imported, avoiding the need to import them individually in each source file.| Module-level| Array| Optional, defaults to an empty array|
16
17### Example
18
19Below provides an example configuration of the **types** Field in **arkOptions**.
20
21Add the **types** field to the **arkOptions** property in the **buildOption** section of the module-level **build-profile.json5** file.
22```json
23// In /entry/build-profile.json5
24{
25  "arkOptions": {
26    "types": ["chai", "./oh_modules/@types/mocha", "./src/main/ets/pages/global"]
27  }
28}
29```
30
31The **types** field can be set to a package name, relative path to a package, or relative path to a declaration file. It supports searches only within the current module. If there are files with the same name but different extensions in a directory, the default loading order is .d.ets > .d.ts.<br>
32(1) Package name: Searches for declaration files defined by the package name in the **oh_modules/@types/** directory, for example, "chai".<br>
33(2) Relative path to a package: Searches for declaration files based on the relative path to **build-profile.json5**, for example, "./oh_modules/@types/mocha".<br>
34(3) Relative path to a declaration file: Searches for declaration files in the specified relative path, for example, "./src/main/ets/pages/global".
35
36### Precautions
37
38If you specify a package name or a relative path to a package in the **types** field, configure **dependencies** in the project-level **/entry/oh-package.json5** file as follows:
39```json
40"dependencies": {
41  "@types/chai": "latest",
42  "@types/mocha": "latest"
43}
44```
45
46If you specify a relative path to a declaration file in the **types** field, ensure the corresponding declaration file exists in the module. Below is the content of a declaration file named **global.d.ts** in **src/main/ets/pages**:
47```typescript
48declare namespace Global {
49  type ObjectType = string | number;
50}
51```
52
53After configuring types, you can use these global types in your code:
54```typescript
55// In entry/src/main/ets/pages/Index.ets
56let a: Chai.Message;
57let b: Mocha.HookFunction;
58let c: Global.ObjectType;
59```
60
61## maxFlowDepth
62
63### Description
64
65Field **maxFlowDepth** in **arkOptions/tscConfig**
66
67| Name| Description| Configuration Scope| Data Type| Optional|
68| -------- | -------- | -------- | -------- | -------- |
69| maxFlowDepth | Specifies the custom maximum stack depth for TSC flow analysis during TSC compilation. It helps avoid stack overflow errors caused by a fixed maximum stack depth. The minimum value is 2000, and the maximum value is 65535.| Project-level| Number| Optional, defaults to 2000.|
70
71### Example
72
73Below provides an example configuration of the **maxFlowDepth** field in **arkOptions/tscConfig**.
74
75Add the **maxFlowDepth** field to the **arkOptions/tscConfig** property in the **buildOption** section of the project-level **build-profile.json5** file.
76
77```typescript
78// In projectName/build-profile.json5
79"arkOptions": {
80  "tscConfig": {
81    "maxFlowDepth": 2222
82  }
83}
84```
85
86### Precautions
87
88- The **maxFlowDepth** field can only be configured in the project-level **build-profile.json5** file.
89- The default value of **maxFlowDepth** is 2000. If the configured value exceeds the allowed range, compilation errors will occur.
90
91  ```txt
92   hvigor ERROR: Schema validate failed.
93    Detail: Please check the following fields.
94      {
95         instancePath: 'app.products[0].buildOption.arkOptions.tscConfig.maxFlowDepth',
96         keyword: 'maximum',
97         params: { comparision: '<=', limit: 65535 },
98         message: 'must be <= 65535',
99         location: 'D:/projectName/build-profile.json5:rowNo:columnNo'
100      }
101  ```
102
103- If the control flow analysis depth in the code exceeds the configured or default value of this field, the analysis will be terminated, and an error will be reported: "The containing function or module body is too large for control flow analysis."
104
105## transformLib
106
107### Description
108
109Field **transformLib** in **arkOptions**
110
111| Name| Description| Configuration Scope| Data Type| Optional|
112| -------- | -------- | -------- | -------- | -------- |
113| transformLib | Specifies the bytecode instrumentation plugin configuration, allowing you to modify bytecode during compilation. This field is supported only in the stage model. The format is a relative path to the dynamic library that does the instrumentation. The dynamic library must be generated on the corresponding platform and cannot be copied or renamed across platforms.| Module-level| String| Optional, defaults to not using this feature|
114
115### Example
116
117Below provides an example configuration of the **transformLib** Field in **arkOptions**.
118
119Add the **transformLib** field to the **arkOptions** property in the **buildOption** section of the module-level **build-profile.json5** file.
120```json
121// In /entry/build-profile.json5
122{
123  "buildOption": {
124    "arkOptions": {
125      "transformLib": "./dll/example.dll"
126    }
127  }
128}
129
130```
131For details about how to modify Ark bytecode, see [Customizing Ark Bytecode During Compilation](customize-bytecode-during-compilation.md).
132
133### Precautions
134
135- If this field is not configured, the feature is not used by default.
136- The configuration takes effect for HAP and HSP modules immediately. For HAR modules, only bytecode HAR configurations are effective; non-bytecode HAR configurations are ignored.
137- The file format must be .dll (for Windows) or .so (for Linux/macOS).
138