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-load Default:False. Help:Stop build until load phase ends
155 --build-only-gn Default:False. Help:Stop build until gn phase ends
156 --build-variant {user,root}
157 Default:'root'. Help:specifies device operating mode
158 --device-type DEVICE_TYPE
159 Default:'default'. Help:specifies device type
160 --disable-package-image
161 deprecated, please do not use this option
162 --archive-image Default:False. Help:archive image when build product complete
163 --rom-size-statistics
164 Default:False. Help:statistics on the actual rom size for each compiled component
165 --stat-ccache Default:True. Help:summary ccache hitrate, and generate ccache.log in ${HOME}/.ccache dir
166 --get-warning-list Default:True. Help:You can use it to collect the build warning and generate WarningList.txt in output dir
167 --generate-ninja-trace {True,False,true,false}
168 Default:True. Help:Count the duration of each ninja thread and generate the ninja trace file(build.trace.gz)
169 --compute-overlap-rate
170 Default:True. Help:Compute overlap rate during the post build
171 --clean-args Default:True. Help:clean all args that generated by this compilation while compilation finished
172 --deps-guard Default:True. Help:simplify code, remove concise dependency analysis, and speed up rule checking
173 --skip-partlist-check Default:False. Help:Skip the subsystem and component check in partlist file
174 ```
175
176 - If you run **hb build** with no argument, the previously configured code directory, product, and options are used for build.
177 - 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**.
178 - You can run **hb build** _\{component_test\}_ to build product component tests separately.
179 - You can run **hb build -p PRODUCT** to skip the setting step and build the product directly.
180 - 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.
181 - 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.
182
183 4. **hb clean**
184
185 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_.
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 This option can be used to:
202 1. View all construction objectives;
203 2. Format .gn file;
204 3. View the dependency path between the construction targets;
205 4. gn build file cleaning.
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## Repositories Involved<a name="section1371113476307"></a>
227**[build](https://gitee.com/openharmony/docs/blob/master/zh-cn/readme/编译构建子系统.md)**
228