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