README.md
1# HB Build Tool Usage Guide<a name="ZH-CN_TOPIC_0000001130006475"></a>
2
3- [Introduction](#section11660541593)
4- [Usage](#section1312121216216)
5 - [Usage Guidelines](#section129654513264)
6
7- [Repositories Involved](#section1371113476307)
8
9## Introduction<a name="section11660541593"></a>
10
11Before compiling and building, you should understand the following basic concepts:
12
13- hb
14
15 A compilation and build script tool developed based on python, which provides features such as compilation environment check and dependency installation, graphical interface compilation guidance, compilation target dependency check, and compilation product cleaning.
16
17- gn
18
19 Gn is the abbreviation of Generate ninja, a meta-building system used to generate ninja files.
20
21- ninja
22
23 Ninja is a small build system focused on speed.
24
25- Component
26
27 Reusable software unit, which can include source code, configuration file, resource file, compilation script, etc.
28
29
30Use hb to start the compilation and construction task flow as follows:
31
321. **hb set**: Set the OpenHarmony source code directory and the product to build.
332. **hb build**: Build the product, development board, or component. The process to build the solution is as follows:
34 - **Reading configuration**: Read the development board configuration, which covers the toolchain, linking commands, and build options.
35 - **Running gn**: Run the **gn gen** command to read the product configuration \(related to the development board, kernel, and system components\) and generate the **out** directory and **ninja** files for the solution.
36 - **Running Ninja**: Run **ninja -C out/company/product** to start build.
37 - **Packaging**: Package the build result to create a file system image.
38
39
40## Usage<a name="section1312121216216"></a>
41
42### Usage Guidelines<a name="section129654513264"></a>
43
441. **Prerequisites**
45 - Server and OS version: Linux server running 64-bit Ubuntu 16.04 or later
46 - Python version: 3.7.4 or later
47 - Repository: **build** source code
48
492. **Installing hb**
50 - Run the following command in the root directory of the source code:
51
52 ```
53 python3 -m pip install --user build/hb
54 ```
55
56 - Run the **hb help** command. If some help information is displayed, the installation is successful. Currently, hb mainly provides five options: hb set, hb build, hb tool, hb env, and hb clean.
57
58
59 - uninstall：
60
61 ```
62 python3 -m pip uninstall ohos-build
63 ```
64
65
663. **Build Commands**
67 1. **hb set**
68
69 ```
70 hb set -h
71 usage: hb set [option]
72
73 options:
74 -h, --help show this help message and exit
75 -p PRODUCT_NAME, --product-name PRODUCT_NAME
76 Default:''. Help:Build a specified product. You could use this option like this: 1.'hb set --product-name rk3568@hihope' 2.'hb set'[graphical ui]
77 --all Default:False. Help:Use a graphical interface to customize most compile-time parameters
78 ```
79
80 - If you run **hb set** with no argument, the default setting process starts.
81 - You can run **hb set -root** _\[ROOT\_PATH\]_ to set the root directory of the source code.
82 - **hb set -p --product** is used to set the product to build.
83 - hb set --all Select customized product configurations, such as product chip architecture, release/debug version, log level, etc.
84
85 2. **hb env**
86
87 Provide compilation environment dependency check and installation
88
89 ```
90 hb env -h
91 usage: hb env [option]
92
93 options:
94 -h, --help show this help message and exit
95 --check Default:True. Help:check that the current running environment contains all dependencies
96 --install Default:False. Help:install all dependent software for compiling products
97 ```
98
99 3. **hb build**
100
101 ```
102 hb build -h
103 usage: hb build [option]
104 options:
105 -h, --help show this help message and exit
106 -p PRODUCT_NAME, --product-name PRODUCT_NAME
107 Default:''. Help:Build a specified product. If you have executed 'hb set', execute 'hb build' directly. Or you could use this option like this: 1.'hb build --product-name rk3568@hihope' 2.'hb build --product-name rk3568'
108 --target-cpu {arm,arm64,x86_64,x64}
109 Default:''. Help:Specifies the desired cpu architecture for the build, each may support different cpu architectures, run 'hb set --all' to list product all supported cpu
110 architectures
111 --rename-last-log {True,False,true,false}
112 Default:True. Help:You can use it to decide whether to keep the last build log
113 --ccache Default:True. Help:Enable ccache, this option could improve compilation speed. --stat-ccache can summary the cache data
114 --enable-pycache {True,False,true,false}
115 Default:False. Help:Enable pycache, This option can improve the execution speed of python files
116 --jobs JOBS Deprecated, please do not use this option
117 --disable-part-of-post-build [DISABLE_PART_OF_POST_BUILD ...]
118 Deprecated, please do not use this option
119 --build-target [BUILD_TARGET ...]
120 Default:[]. Help:You use this option to specify a single compilation target, and use 'hb tool --ls' to list all build target
121 --ninja-args [NINJA_ARGS ...]
122 Default:[]. Help:You can use it to pass parameters for the ninja phase, but you need to follow the specified command format. eg. --ninja-args=-dkeeprsp
123 -f, --full-compilation
124 Default:[]. Help:You can use it to start full code compilation. The default compilation target is images. Use this option to add 'make_all' and 'make_test' to the build
125 process.
126 --strict-mode {True,False,true,false}
127 Default:False. Help:Check all produce of each phase to early terminates a potentially problematic compilation.
128 --scalable-build {True,False,true,false}
129 Default:False. Help:Select whether to read information from parts.json generate by preload
130 --build-example {True,False,true,false}
131 Default:False. Help:Select whether to read information from subsystem_config_example.json
132 --build-platform-name BUILD_PLATFORM_NAME
133 Default:'phone'. Help:Name of the compilation platform. The current optional value is 'phone'
134 --build-xts {True,False,true,false}
135 Default:False. Help:Select whether to load the components included in the subsystem xts
136 --ignore-api-check [IGNORE_API_CHECK ...]
137 Default:[]. Help:Skip the check of some subsystems
138 --load-test-config {True,False,true,false}
139 Default:True. Help:Select whether to load the test field in bundle.json, that is, whether to call the test case
140 --build-type {release,debug}
141 Default:'release'. Help:Specify compile release or debug version
142 --log-level {info,debug}
143 Default:'INFO'. Help:Specify the log level during compilation. you can select two levels: debug, info. In debug mode, it show all command lines while building, including
144 cxx, link, solink, etc.
145 --export-para [EXPORT_PARA ...]
146 Deprecated, please do not use this option
147 --test [TEST ...] Default:[]. Help:You can use it to choose test type. eg. --test xts
148 --gn-args [GN_ARGS ...]
149 Default:[]. Help:Specify gn build arguments, you could use this option like this 'hb build --gn-args is_debug=true'
150 -c COMPILER, --compiler COMPILER
151 Deprecated, please do not use this option
152 --fast-rebuild Default:False. Help:You can use it to skip prepare, preloader, gn_gen steps so we can enable it only when there is no change for gn related script
153 --keep-ninja-going Default:False. Help:When you need to debug one specific target, you can use this option to keep ninja going to skip some possible error until 1000000 jobs fail
154 --build-only-gn Default:False. Help:Stop build until gn phase ends
155 --build-variant {user,root}
156 Default:'root'. Help:specifies device operating mode
157 --device-type DEVICE_TYPE
158 Default:'default'. Help:specifies device type
159 --disable-package-image
160 deprecated, please do not use this option
161 --archive-image Default:False. Help:archive image when build product complete
162 --rom-size-statistics
163 Default:False. Help:statistics on the actual rom size for each compiled component
164 --stat-ccache Default:True. Help:summary ccache hitrate, and generate ccache.log in ${HOME}/.ccache dir
165 --get-warning-list Default:True. Help:You can use it to collect the build warning and generate WarningList.txt in output dir
166 --generate-ninja-trace {True,False,true,false}
167 Default:True. Help:Count the duration of each ninja thread and generate the ninja trace file(build.trace.gz)
168 --compute-overlap-rate
169 Default:True. Help:Compute overlap rate during the post build
170 --clean-args Default:True. Help:clean all args that generated by this compilation while compilation finished
171 --deps-guard Default:True. Help:simplify code, remove concise dependency analysis, and speed up rule checking
172 --skip-partlist-check Default:False. Help:Skip the subsystem and component check in partlist file
173 ```
174
175 - If you run **hb build** with no argument, the previously configured code directory, product, and options are used for build.
176 - You can run **hb build** _\{component\}_ to build product components separately based on the development board and kernel set for the product, for example, **hb build kv\_store**.
177 - You can run **hb build** _\{component_test\}_ to build product component tests separately.
178 - You can run **hb build -p PRODUCT** to skip the setting step and build the product directly.
179 - You can run **hb build** in **device/device\_company/board** to select the kernel and start build based on the current development board and the selected kernel to generate an image that contains the kernel and driver only.
180 - When hb build is executed in the component directory, it will detect whether bundle.json exists in the current directory. If it exists, it will compile the current component separately as the compilation target without switching to the source code root directory for execution.
181
182 4. **hb clean**
183
184 Clear the build result of the product in the **out** directory, and leave the **args.gn** and **build.log** files only. To clear files in a specified directory, add the directory parameter to the command, for example, **hb clean** _xxx_**/out/**_xxx_.
185
186 ```
187 hb clean -h
188 usage: hb clean [option]
189
190 options:
191 -h, --help show this help message and exit
192 --clean-all Default:False. Help:clean all producer
193 --clean-args Default:True. Help:clean all args that generated by last compilation
194 --clean-out-product Default:False. Help:clean out/{product} directory that generated by last compilation
195 --clean-ccache Default:False. Help:clean .ccache directory which is in OHOS root
196 ```
197
198 5. **hb tool**
199
200 This option can be used to:
201 1. View all construction objectives;
202 2. Format .gn file;
203 3. View the dependency path between the construction targets;
204 4. gn build file cleaning.
205 ```
206 hb tool -h
207 usage: hb tool [option]
208
209 options:
210 -h, --help show this help message and exit
211 --ls [LS ...] Default:[]. Help:Lists all targets matching the given pattern for the given build directory. You could use this option like this: 1.'hb tool --ls <out_dir> [<label_pattern>]
212 [<options>]'
213 --desc [DESC ...] Default:[]. Help:Displays information about a given target or config. You could use this option like this: 1.'hb tool --desc <out_dir> <component_module> [<what to show>]
214 [<options>]'
215 --path [PATH ...] Default:[]. Help:Finds paths of dependencies between two targets. You could use this option like this: 1.'hb tool --path <out_dir> <component1_module1> <component2_module2>
216 [<options>]'
217 --refs [REFS ...] Default:[]. Help:Finds reverse dependencies (which targets reference something). You could use this option like this: 1.'hb tool --refs <out_dir> [<component_module>|<file>]
218 [<options>]'
219 --format [FORMAT ...]
220 Default:[]. Help:Formats .gn file to a standard format. You could use this option like this: 1.'hb tool --format /abspath/some/BUILD.gn [<options>]'
221 --clean CLEAN Default:[]. Help:Deletes the contents of the output directory except for args.gn. You could use this option like this: 1.'hb tool --clean <out_dir>'
222 ```
223
224
225## Repositories Involved<a name="section1371113476307"></a>
226**[build](https://gitee.com/openharmony/docs/blob/master/zh-cn/readme/编译构建子系统.md)**
227
README_zh.md
1# HB构建工具使用指导<a name="ZH-CN_TOPIC_0000001130006475"></a>
2
3- [简介](#section11660541593)
4- [说明](#section1312121216216)
5 - [使用说明](#section129654513264)
6
7- [相关仓](#section1371113476307)
8
9## 简介<a name="section11660541593"></a>
10
11在开发编译构建前，应了解如下基本概念：
12
13- hb
14
15 一款基于python开发的编译构建脚本工具，提供了编译环境检查与依赖安装、图形化界面编译引导、编译目标依赖检查、编译产物清理等特性。
16
17- gn
18
19 Generate ninja的缩写，一种元构建系统，用于产生ninja文件。
20
21- ninja
22
23 ninja是一个专注于速度的小型构建系统。
24
25- 部件
26
27 可复用的软件单元，它可包含源码、配置文件、资源文件和编译脚本等。
28
29
30使用hb启动编译构建任务流程如下：
31
321. hb set: 设置源码目录和要编译的产品。
332. hb build: 编译产品、开发板或者组件。解决方案编译实现如下：
34 - 读取开发板配置：主要包括开发板使用的编译工具链、编译链接命令和选项等。
35 - 调用gn: 调用gn gen命令，读取产品配置\(主要包括开发板、内核、选择的组件等\)生成解决方案out目录和ninja文件。
36 - 调用ninja：调用ninja -C out/company/product启动编译。
37 - 系统镜像打包：将组件编译产物打包，制作文件系统镜像。
38
39
40## 说明<a name="section1312121216216"></a>
41
42### 使用说明<a name="section129654513264"></a>
43
441. **前提条件**
45 - Linux服务器，Ubuntu16.04及以上64位系统版本。
46 - Python 3.7.4及以上。
47 - 源码下载成功。
48
492. **安装hb**
50 - 在源码根目录下执行：
51
52 ```
53 python3 -m pip install --user build/hb
54 ```
55
56 - 执行hb help有相关帮助信息，有打印信息即表示安装成功，当前hb 主要提供了hb set，hb build，hb tool，hb env，hb clean五个选项。
57
58
59 - 卸载方法：
60
61 ```
62 python3 -m pip uninstall ohos-build
63 ```
64
65
663. **编译命令**
67 1. **hb set**
68
69 ```
70 hb set -h
71 usage: hb set [option]
72
73 options:
74 -h, --help show this help message and exit
75 -p PRODUCT_NAME, --product-name PRODUCT_NAME
76 Default:''. Help:Build a specified product. You could use this option like this: 1.'hb set --product-name rk3568@hihope' 2.'hb set'[graphical ui]
77 --all Default:False. Help:Use a graphical interface to customize most compile-time parameters
78 ```
79
80 - hb set 后无参数，进入默认设置流程
81 - hb set -root \[ROOT\_PATH\] 直接设置代码根目录
82 - hb set -p --product 设置要编译的产品
83 - hb set --all 选择自定义的产品配置，如产品芯片架构、release/debug版本、日志级别等
84
85 2. **hb env**
86
87 提供编译环境依赖检查和安装
88
89 ```
90 hb env -h
91 usage: hb env [option]
92
93 options:
94 -h, --help show this help message and exit
95 --check Default:True. Help:check that the current running environment contains all dependencies
96 --install Default:False. Help:install all dependent software for compiling products
97 ```
98
99 3. **hb build**
100
101 ```
102 hb build -h
103 usage: hb build [option]
104 options:
105 -h, --help show this help message and exit
106 -p PRODUCT_NAME, --product-name PRODUCT_NAME
107 Default:''. Help:Build a specified product. If you have executed 'hb set', execute 'hb build' directly. Or you could use this option like this: 1.'hb build --product-name rk3568@hihope' 2.'hb build --product-name rk3568'
108 --target-cpu {arm,arm64,x86_64,x64}
109 Default:''. Help:Specifies the desired cpu architecture for the build, each may support different cpu architectures, run 'hb set --all' to list product all supported cpu
110 architectures
111 --rename-last-log {True,False,true,false}
112 Default:True. Help:You can use it to decide whether to keep the last build log
113 --ccache Default:True. Help:Enable ccache, this option could improve compilation speed. --stat-ccache can summary the cache data
114 --enable-pycache {True,False,true,false}
115 Default:False. Help:Enable pycache, This option can improve the execution speed of python files
116 --jobs JOBS Deprecated, please do not use this option
117 --disable-part-of-post-build [DISABLE_PART_OF_POST_BUILD ...]
118 Deprecated, please do not use this option
119 --build-target [BUILD_TARGET ...]
120 Default:[]. Help:You use this option to specify a single compilation target, and use 'hb tool --ls' to list all build target
121 --ninja-args [NINJA_ARGS ...]
122 Default:[]. Help:You can use it to pass parameters for the ninja phase, but you need to follow the specified command format. eg. --ninja-args=-dkeeprsp
123 -f, --full-compilation
124 Default:[]. Help:You can use it to start full code compilation. The default compilation target is images. Use this option to add 'make_all' and 'make_test' to the build
125 process.
126 --strict-mode {True,False,true,false}
127 Default:False. Help:Check all produce of each phase to early terminates a potentially problematic compilation.
128 --scalable-build {True,False,true,false}
129 Default:False. Help:Select whether to read information from parts.json generate by preload
130 --build-example {True,False,true,false}
131 Default:False. Help:Select whether to read information from subsystem_config_example.json
132 --build-platform-name BUILD_PLATFORM_NAME
133 Default:'phone'. Help:Name of the compilation platform. The current optional value is 'phone'
134 --build-xts {True,False,true,false}
135 Default:False. Help:Select whether to load the components included in the subsystem xts
136 --ignore-api-check [IGNORE_API_CHECK ...]
137 Default:[]. Help:Skip the check of some subsystems
138 --load-test-config {True,False,true,false}
139 Default:True. Help:Select whether to load the test field in bundle.json, that is, whether to call the test case
140 --build-type {release,debug}
141 Default:'release'. Help:Specify compile release or debug version
142 --log-level {info,debug}
143 Default:'INFO'. Help:Specify the log level during compilation. you can select two levels: debug, info. In debug mode, it show all command lines while building, including
144 cxx, link, solink, etc.
145 --export-para [EXPORT_PARA ...]
146 Deprecated, please do not use this option
147 --test [TEST ...] Default:[]. Help:You can use it to choose test type. eg. --test xts
148 --gn-args [GN_ARGS ...]
149 Default:[]. Help:Specify gn build arguments, you could use this option like this 'hb build --gn-args is_debug=true'
150 -c COMPILER, --compiler COMPILER
151 Deprecated, please do not use this option
152 --fast-rebuild Default:False. Help:You can use it to skip prepare, preloader, gn_gen steps so we can enable it only when there is no change for gn related script
153 --keep-ninja-going Default:False. Help:When you need to debug one specific target, you can use this option to keep ninja going to skip some possible error until 1000000 jobs fail
154 --build-only-gn Default:False. Help:Stop build until gn phase ends
155 --build-variant {user,root}
156 Default:'root'. Help:specifies device operating mode
157 --device-type DEVICE_TYPE
158 Default:'default'. Help:specifies device type
159 --disable-package-image
160 deprecated, please do not use this option
161 --archive-image Default:False. Help:archive image when build product complete
162 --rom-size-statistics
163 Default:False. Help:statistics on the actual rom size for each compiled component
164 --stat-ccache Default:True. Help:summary ccache hitrate, and generate ccache.log in ${HOME}/.ccache dir
165 --get-warning-list Default:True. Help:You can use it to collect the build warning and generate WarningList.txt in output dir
166 --generate-ninja-trace {True,False,true,false}
167 Default:True. Help:Count the duration of each ninja thread and generate the ninja trace file(build.trace.gz)
168 --compute-overlap-rate
169 Default:True. Help:Compute overlap rate during the post build
170 --clean-args Default:True. Help:clean all args that generated by this compilation while compilation finished
171 --deps-guard Default:True. Help:simplify code, remove concise dependency analysis, and speed up rule checking
172 --skip-partlist-check Default:False. Help:Skip the subsystem and component check in partlist file
173
174 ```
175
176 - hb build后无参数，会按照设置好的代码路径、产品进行编译，编译选项使用与之前保持一致。
177 - hb build component：基于设置好的产品对应的单板、内核，单独编译组件（e.g.：hb build kv\_store\)。
178 - hb build component_test: 基于设置好的产品对应的单板、内核，单独编译组件的测试用例。
179 - hb build -p PRODUCT：免set编译产品，该命令可以跳过set步骤，直接编译产品。
180 - 在device/device\_company/board下单独执行hb build会进入内核选择界面，选择完成后会根据当前路径的单板、选择的内核编译出仅包含内核、驱动的镜像。
181 - hb build在部件目录下执行，会检测当前目录下是否存在bundle.json，如果存在，则会将当前部件作为编译目标单独编译，而无须切换至源码根目录下执行。
182
183 4. **hb clean**
184
185 清除out目录对应产品的编译产物，仅剩下args.gn、build.log。清除指定路径可输入路径参数：hb clean xxx/out/xxx，否则将清除hb set的产品对应out路径
186
187 ```
188 hb clean -h
189 usage: hb clean [option]
190
191 options:
192 -h, --help show this help message and exit
193 --clean-all Default:False. Help:clean all producer
194 --clean-args Default:True. Help:clean all args that generated by last compilation
195 --clean-out-product Default:False. Help:clean out/{product} directory that generated by last compilation
196 --clean-ccache Default:False. Help:clean .ccache directory which is in OHOS root
197 ```
198
199 5. **hb tool**
200
201 该选项可以用于：
202 1. 查看所有构建目标；
203 2. .gn文件格式化；
204 3. 查看构建目标之间的依赖关系路径；
205 4. gn构建文件清理。
206 ```
207 hb tool -h
208 usage: hb tool [option]
209
210 options:
211 -h, --help show this help message and exit
212 --ls [LS ...] Default:[]. Help:Lists all targets matching the given pattern for the given build directory. You could use this option like this: 1.'hb tool --ls <out_dir> [<label_pattern>]
213 [<options>]'
214 --desc [DESC ...] Default:[]. Help:Displays information about a given target or config. You could use this option like this: 1.'hb tool --desc <out_dir> <component_module> [<what to show>]
215 [<options>]'
216 --path [PATH ...] Default:[]. Help:Finds paths of dependencies between two targets. You could use this option like this: 1.'hb tool --path <out_dir> <component1_module1> <component2_module2>
217 [<options>]'
218 --refs [REFS ...] Default:[]. Help:Finds reverse dependencies (which targets reference something). You could use this option like this: 1.'hb tool --refs <out_dir> [<component_module>|<file>]
219 [<options>]'
220 --format [FORMAT ...]
221 Default:[]. Help:Formats .gn file to a standard format. You could use this option like this: 1.'hb tool --format /abspath/some/BUILD.gn [<options>]'
222 --clean CLEAN Default:[]. Help:Deletes the contents of the output directory except for args.gn. You could use this option like this: 1.'hb tool --clean <out_dir>'
223 ```
224
225
226## 相关仓<a name="section1371113476307"></a>
227**[编译构建子系统](https://gitee.com/openharmony/docs/blob/master/zh-cn/readme/编译构建子系统.md)**
228