README_zh.md
1# 预编译工具配置指南
2- [工具下载配置](#section-download-01)
3 1. [核心配置说明](#section-download-core-01)
4 2. [基础配置示例](#section-download-basic-demo)
5 3. [高级配置示例](#section-download-advanced-demo)
6- [处理配置](#advanced-process)
7- [变量处理](#value-search)
8
9## 工具下载配置 <a name="section-download-01"></a>
10下载配置用于配置下载和解压参数
11### 核心配置项说明 <a name="section-download-core-01"></a>
12
13|参数|描述|
14|--|--|
15remote_url|远程包下载地址|
16unzip_dir|解压目标路径|
17unzip_filename|解压后的顶层目录名（用于版本管理和旧文件清理）|
18
19### 基础配置示例 <a name="section-download-basic-demo"></a>
20#### 场景1：指定操作系统与CPU架构 <a name="section-download-basic-demo-01"></a>
21以 ark_js_prebuilts 工具为例，在 Linux x86_64 环境下的配置如下：
22```json
23{
24 "name": "ark_js_prebuilts",
25 "tag": "base",
26 "type": "src, indep",
27 "config": {
28 "linux": {
29 "x86_64": {
30 "remote_url": "/openharmony/compiler/llvm_prebuilt_libs/ark_js_prebuilts_20230713.tar.gz",
31 "unzip_dir": "${code_dir}/prebuilts/ark_tools",
32 "unzip_filename": "ark_js_prebuilts"
33 }
34 }
35 }
36}
37```
38
39
40#### 场景2：CPU架构无关配置 <a name="section-download-basic-demo-02"></a>
41若工具包不依赖CPU架构（如纯脚本工具），可省略架构标识
42``` json
43{
44 "name": "ark_js_prebuilts",
45 "tag": "base",
46 "type": "src, indep",
47 "config": {
48 "linux": {
49 "remote_url": "/openharmony/compiler/llvm_prebuilt_libs/ark_js_prebuilts_20230713.tar.gz",
50 "unzip_dir": "${code_dir}/prebuilts/ark_tools",
51 "unzip_filename": "ark_js_prebuilts"
52 }
53 }
54}
55```
56
57
58#### 场景3：平台无关配置 <a name="section-download-basic-demo-03"></a>
59若工具包和平台无关，配置进一步简化：
60```json
61{
62 "name": "ark_js_prebuilts",
63 "tag": "base",
64 "type": "src, indep",
65 "remote_url": "/openharmony/compiler/llvm_prebuilt_libs/ark_js_prebuilts_20230713.tar.gz",
66 "unzip_dir": "${code_dir}/prebuilts/ark_tools",
67 "unzip_filename": "ark_js_prebuilts"
68}
69```
70
71### 高级配置场景 <a name="section-download-advanced-demo"></a>
72#### 多版本并行下载（以LLVM为例）<a name="section-download-advanced-demo-01"></a>
73若需在同一平台下安装多个版本，配置项改为列表形式：
74```json
75{
76 "name": "llvm",
77 "tag": "base",
78 "type": "src, indep",
79 "config": {
80 "linux": {
81 "x86_64": [
82 {
83 "remote_url": "/openharmony/compiler/clang/15.0.4-3cec00/ohos_arm64/clang_ohos-arm64-3cec00-20250320.tar.gz",
84 "unzip_dir": "${code_dir}/prebuilts/clang/ohos/ohos-arm64",
85 "unzip_filename": "llvm",
86 },
87 {
88 "remote_url": "/openharmony/compiler/clang/15.0.4-3cec00/windows/clang_windows-x86_64-3cec00-20250320.tar.gz",
89 "unzip_dir": "${code_dir}/prebuilts/clang/ohos/windows-x86_64",
90 "unzip_filename": "llvm",
91 },
92 {
93 "remote_url": "/openharmony/compiler/clang/15.0.4-3cec00/linux/clang_linux-x86_64-3cec00-20250320.tar.gz",
94 "unzip_dir": "${code_dir}/prebuilts/clang/ohos/linux-x86_64",
95 "unzip_filename": "llvm",
96 }
97 ]
98 }
99 }
100}
101```
102
103
104
105#### 使用公共配置 <a name="section-common-var"></a>
106当配置中存在值相同的配置项时，可提取公共配置避免冗余：<br>
107**原始冗余配置**
108```json
109{
110 "name": "ark_js_prebuilts",
111 "tag": "base",
112 "type": "src, indep",
113 "config": {
114 "linux": {
115 "x86_64": {
116 "remote_url": "/openharmony/compiler/llvm_prebuilt_libs/ark_js_prebuilts_20230713.tar.gz",
117 "unzip_dir": "${code_dir}/prebuilts/ark_tools",
118 "unzip_filename": "ark_js_prebuilts"
119 }
120 },
121 "darwin": {
122 "x86_64": {
123 "remote_url": "/openharmony/compiler/llvm_prebuilt_libs/ark_js_prebuilts_darwin_x64_20230209.tar.gz",
124 "unzip_dir": "${code_dir}/prebuilts/ark_tools",
125 "unzip_filename": "ark_js_prebuilts"
126 }
127 }
128 }
129}
130```
131
132**优化后配置**
133```json
134{
135 "name": "ark_js_prebuilts",
136 "tag": "base",
137 "type": "src, indep",
138 "unzip_dir": "${code_dir}/prebuilts/ark_tools",
139 "unzip_filename": "ark_js_prebuilts",
140 "config": {
141 "linux": {
142 "x86_64": {
143 "remote_url": "/openharmony/compiler/llvm_prebuilt_libs/ark_js_prebuilts_20230713.tar.gz"
144 }
145 },
146 "darwin": {
147 "x86_64": {
148 "remote_url": "/openharmony/compiler/llvm_prebuilt_libs/ark_js_prebuilts_darwin_x64_20230209.tar.gz"
149
150 }
151 }
152 }
153}
154```
155
156#### 配置继承规则 <a name="section-inherit"></a>
157- 工具配置会继承全局配置
158- 平台配置会继承工具配置
159- 存在相同配置项时，内部配置会覆盖继承的配置
160#### 说明
161- 全局配置在工具配置的外层定义
162- 平台配置在config里面定义
163- 除config和handle，都属于工具配置
164
165## 处理配置 <a name="advanced-process"></a>
166部分工具在下载解压完成后需要进行额外的处理，这些处理操作可以在handle中定义，handle会在下载解压完成后执行，若没有下载解压操作，handle则会直接执行。handle是一个列表，其中的每一项都代表一个操作
167### handle配置特点 <a name="advanced-process-handle-feature"></a>
168- 顺序执行：操作项按配置顺序依次执行
169- 使用变量：操作中可使用外部变量
170- 灵活控制：平台配置中可通过指定handle_index，定制操作序列
171- 容错机制：若操作中的变量解析失败，跳过当前操作
172
173### 公共操作列表 <a name="advanced-process-common-operate"></a>
174
175|操作类型|参数|用途|
176|-|-|-|
177|symlink| src: 链接源<br>dest: 目的链接地址| 生成符号链接
178|copy | src: 源<br>dest: 目的| 复制文件或文件夹 |
179|remove | path:要删除的路径, 可以是字符串，也可以是一个列表 | 删除文件或文件夹 |
180|move | src: 源路径<br>dest: 目标路径<br>filetype: 该参数默认不填写，若填写，则只会移动src目录中以filetype为后缀的文件 | 移动文件,若dest是个已存在的目录，则会移动到目录中 |
181|shell | cmd: 命令(列表形式) |执行shell命令
182
183### handle配置示例 <a name="advanced-process-demo"></a>
184#### 场景： 解压Node工具后创建符号链接: <a name="advanced-process-demo-01"></a>
185```json
186{
187 "name": "node",
188 "tag": "base",
189 "type": "src, indep",
190 "unzip_dir": "${code_dir}/prebuilts/build-tools/common/nodejs",
191 "config": {
192 "linux": {
193 "x86_64": [
194 {
195 "remote_url": "/nodejs/v14.21.1/node-v14.21.1-linux-x64.tar.gz",
196 "unzip_filename": "node-v14.21.1-linux-x64",
197 "symlink_src": "${code_dir}/prebuilts/build-tools/common/nodejs/node-v14.21.1-linux-x64"
198 }
199 ]
200 }
201 },
202 "handle": [
203 {
204 "type": "symlink",
205 "src": "${symlink_src}",
206 "dest": "${code_dir}/prebuilts/build-tools/common/nodejs/current"
207 }
208 ]
209}
210```
211
212
213## 变量处理 <a name="value-search"></a>
214- 变量只能使用${var_name}的方式指定
215- 工具配置可以使用自身内部以及全局配置中的变量
216- 平台配置可以使用自身内部、工具以及全局配置中的变量
217- handl中的操作项可以使用自身内部、平台、工具以及全局配置中的变量
218- 变量解析优先级为：自身内部配置 > 平台配置 > 工具配置 > 全局配置
219