1# Compilation and Building Guide 2 3## Overview 4 5The OpenHarmony Compilation and Building subsystem provides a build framework based on Generate Ninja (GN) and Ninja. It abstracts the build and configuration granularity by component, and provides function enhancement for built-in modules and function extension for service modules. The OpenHarmony Compilation and Building subsystem provides the following functions: 6 7- Allows products to be assembled and independently built by component. 8- Supports version builds for mini, small, and standard systems and build of the software development kit (SDK), which facilitates application developers to use the Integrated development environment (IDE). 9- Supports customization and independent build based on different chipset solutions. 10 11### Application Scope 12 13This guide is applicable to mini, small, and standard systems. The [Chipset Solution](subsys-build-chip_solution.md) applies only to mini and small systems. 14 15### Basic Concepts 16 17 18Learn the following basic concepts before you get started: 19 20- Platform 21 22 A platform consists of a development board and the kernel. The subsystems and components vary with the platform. 23 24- Product 25 26 A product is a collection of components. The product image built can run on different development boards. 27 28- Subsystem 29 30 OpenHarmony is designed with a layered architecture, which consists of the kernel layer, system service layer, framework layer, and application layer from bottom up. For details, see [OpenHarmony Technical Architecture](https://gitee.com/openharmony#technical-architecture). System functions are built from components, subsystems, and then to the system. In a multi-device deployment, you can customize subsystems and components as required. A subsystem, as a logical concept, consists of the least required components. 31 32- Component 33 34 A component is a reusable software binary unit that contains source code, configuration files, resource files, and build scripts. It can be built independently, integrated in binary mode, and tested independently. The chipset solution mentioned in this guide is a special component in nature. 35 36- Module 37 38 A module is a target to build. A component can also be a target to build. 39 40- Feature 41 42 A component can provide differentiated functions through features. 43 44- GN 45 46 GN is used to generate Ninja files. 47 48- Ninja 49 50 Ninja is a small high-speed build system. 51 52- hb 53 54 hb is an OpenHarmony command line tool used to execute build commands. 55 56The Compilation and Build subsystem implements compilation and packaging through configuration. The following describes the relationships between the product, subsystem, component, and module. 57 58**Figure 1** Relationships between product, subsystem, component, and module 59 60 61 62The relationships between the product, subsystem, component, and module are as follows: 63 64- A subsystem is a collection of all components. A component can belong to only one subsystem. 65- A component is a collection of modules. A module can belong to only one component. 66- The product configuration file contains the configuration of all the components of the product. The component configuration can be reused. 67- A component used in different products can provide differentiated functions through variants or features. 68- A module is a target to build, and a component can also be a target to build. 69 70### Working Principles 71 72A product, component, and module can be built, but a subsystem cannot. The figure below shows the build process. 73 74**Figure 2** Build process 75 76 77 781. Run **hb set** to set the product to build. 79 802. Use **hb build** to build a product, development board, or component. 81 82 The procedure is as follows: 83 84 1. Read the **config.gni** file of the development board selected. The file contains the build toolchain, linking commands, and build options. 85 2. Run the **gn gen** command to read the product configuration and generate the **out** directory and **ninja** files for the product solution. 86 3. Run **ninja -C out/board/product** to start the build. 87 4. Package the files built, set the file attributes and permissions, and create a file system image. 88 89### Constraints 90 91Currently, only Ubuntu18.04 and Ubuntu20.04 are supported. Ubuntu22.04 is not supported. 92 93### Environment Configuration 94 95You must install the software packages required for build. The command is as follows: 96 97- Method 1: Run the script in the project directory. 98 ```shell 99 ./build/build_scripts/env_setup.sh 100 ``` 101 102- Method 2: Run the **apt-get install** and **pip3 install** commands. 103 ```shell 104 apt-get update -y 105 apt-get install -y 106 # Install Python 3.9 for Ubuntu 20.04, and install Python 3.8 for Ubuntu 18.04. 107 apt-get install -y apt-utils binutils bison flex bc build-essential make mtd-utils gcc-arm-linux-gnueabi u-boot-tools python3.9 python3-pip git zip unzip curl wget gcc g++ ruby dosfstools mtools default-jre default-jdk scons python3-distutils perl openssl libssl-dev cpio git-lfs m4 ccache zlib1g-dev tar rsync liblz4-tool genext2fs binutils-dev device-tree-compiler e2fsprogs git-core gnupg gnutls-bin gperf lib32ncurses5-dev libffi-dev zlib* libelf-dev libx11-dev libgl1-mesa-dev lib32z1-dev xsltproc x11proto-core-dev libc6-dev-i386 libxml2-dev lib32z-dev libdwarf-dev 108 apt-get install -y grsync xxd libglib2.0-dev libpixman-1-dev kmod jfsutils reiserfsprogs xfsprogs squashfs-tools pcmciautils quota ppp libtinfo-dev libtinfo5 libncurses5 libncurses5-dev libncursesw5 libstdc++6 gcc-arm-none-eabi vim ssh locales doxygen 109 apt-get install -y libxinerama-dev libxcursor-dev libxrandr-dev libxi-dev 110 # The following modules must be installed for Python. You can obtain the repo file from the source code of the build environment you use. 111 chmod +x /usr/bin/repo 112 pip3 install --trusted-host https://repo.huaweicloud.com -i https://repo.huaweicloud.com/repository/pypi/simple requests setuptools pymongo kconfiglib pycryptodome ecdsa ohos-build pyyaml prompt_toolkit==1.0.14 redis json2html yagmail python-jenkins 113 pip3 install esdk-obs-python --trusted-host pypi.org 114 pip3 install six --upgrade --ignore-installed six 115 #Install LLVM, hc-gen, gcc_riscv32, Ninja, node-v14.15.4-linux-x64, and GN. If the shell in use is not bash or zsh, configure the following environment variables: 116 # export PATH=/home/tools/llvm/bin:$PATH 117 # export PATH=/home/tools/hc-gen:$PATH 118 # export PATH=/home/tools/gcc_riscv32/bin:$PATH 119 # export PATH=/home/tools/ninja:$PATH 120 # export PATH=/home/tools/node-v12.20.0-linux-x64/bin:$PATH 121 # export PATH=/home/tools/gn:$PATH 122 # export PATH=~/.local/bin:$PATH 123 ``` 124 125  **NOTE**<br>The hb tool will be installed during the installation of **ohos-build**. If hb tool fails to be installed, [install hb](../../device-dev/quick-start/quickstart-pkg-install-tool.md#hb-installation) again. 126 127 128## Configuration Rules 129 130To ensure that chipset and product solutions are decoupled from OpenHarmony, you need to follow certain rules during the configuration. 131 132- [Product Configuration Rules](subsys-build-product.md#configuration-rules) 133- [Subsystem Configuration Rules](subsys-build-subsystem.md#configuration-rules) 134- [Component Configuration Rules](subsys-build-component.md#configuration-rules) 135- [Module Configuration Rules](subsys-build-module.md#configuration-rules) 136- [Chipset Solution Configuration Rules](subsys-build-chip_solution.md#configuration-rules) 137- [Feature Configuration Rules](subsys-build-feature.md#configuration-rules) 138- [System Capability Configuration Rules](subsys-build-syscap.md) 139 140## Guidelines 141 142### Directory Structure 143 144```shell 145 146/build # Directory for build 147 148├── __pycache__ 149├── build_scripts/ # Python scripts for build 150├── common/ 151├── config/ # Build-related configuration 152├── core 153│ └── gn/ # BUILD.gn configuration 154 └── build_scripts/ 155├── docs 156gn_helpers.py* 157lite/ # hb and preloader entry 158misc/ 159├── ohos # Configuration of OpenHarmony build and packaging 160│ ├── kits # Kits build and packaging templates and processing 161│ ├── ndk # NDK templates and processing 162│ ├── notice # Notice templates and processing 163│ ├── packages # Distribution packaging templates and processing 164│ ├── sa_profile # SA profiles and processing 165│ ├── sdk # SDK templates and processing, which contains the module configuration in the SDK 166│ └── testfwk # Testing-related processing 167├── ohos.gni* # Common .gni files (facilitating one-time import of each module) 168├── ohos_system.prop 169├── ohos_var.gni* 170├── prebuilts_download.sh* 171├── print_python_deps.py* 172├── scripts/ 173├── subsystem_config.json 174├── subsystem_config_example.json 175├── templates/ # C/C++ build templates 176├── test.gni* 177├── toolchain # Build toolchain configuration 178├── tools # Common tools 179├── version.gni 180├── zip.py* 181 182``` 183 184 185 186### Build Commands 187 188Run the **prebuilts** script in the root directory of the source code to perform precompilation and install the compiler and binary tool. 189 190```shell 191bash build/prebuilts_download.sh 192``` 193 194Then, run the build commands in command line (CLI) mode or hb mode. 195 1961. Using the CLI 197 198- Run the following command in the root directory of the source code to build a full distribution: 199 200 Release version: 201 ```shell 202 ./build.sh --product-name {product_name} 203 ``` 204 Debug version: 205 ```shell 206 ./build.sh --product-name {product_name} --gn-args is_debug=true 207 ``` 208 >  **CAUTION**<br/> 209 > Due to the limitation of the image size, the full build for the debug version may fail to be burnt. You are advised to build the binary file for each module separately. Run the following command to build a module separately: 210 > 211 > 212 > ``` 213 > ./build.sh --product-name {product_name} --gn-args is_debug=true --build-target {target_name} 214 > ``` 215 > 216 **{product_name}** specifies the product platform supported by the current distribution, for example, **hispark_taurus_standard**. 217 218 The image generated is stored in the **out/{device_name}/packages/phone/images/** directory. 219 220 221 222- The **./build.sh** command supports the following options: 223 224 ```shell 225 -h, --help # Display help information and exit. 226 --source-root-dir=SOURCE_ROOT_DIR # Specify the path. 227 --product-name=PRODUCT_NAME # Specify the product name. 228 --device-name=DEVICE_NAME # Specify the device name. 229 --target-cpu=TARGET_CPU # Specify the CPU. 230 --target-os=TARGET_OS # Specify the operating system. 231 -T BUILD_TARGET, --build-target=BUILD_TARGET # Specify one or more targets to build. 232 --gn-args=GN_ARGS # Specify GN parameters. 233 --ninja-args=NINJA_ARGS # Specify Ninja parameters. 234 -v, --verbose # Display all commands used. 235 --keep-ninja-going # Keep Ninja going until 1,000,000 jobs fail. 236 --jobs=JOBS 237 --export-para=EXPORT_PARA 238 --build-only-gn # Perform GN parsing and do not run Ninja. 239 --ccache # (Optional) Use ccache for build. You need to install ccache locally. 240 --fast-rebuild # Specify whether to allow fast rebuild. The default value is False. 241 --log-level=LOG_LEVEL # Specify the log level used in the build process. The options are debug, info, and error. The default value is info. 242 --device-type=DEVICE_TYPE # Specify the device type. The default value is default. 243 --build-variant=BUILD_VARIANT # Specify the device operation mode. The default value is user. 244 ``` 245 2462. Using the hb tool 247 248**hb** is an OpenHarmony command line tool for executing build commands. Common hb commands are described as follows: 249 250**hb set** 251 252Sets the product to build. 253 254```shell 255hb set -h 256usage: hb set [-h] [-root [ROOT_PATH]] [-p] 257 258optional arguments: 259 -h, --help show this help message and exit 260 -root [ROOT_PATH], --root_path [ROOT_PATH] 261 Set OHOS root path 262 -p, --product Set OHOS board and kernel 263``` 264 265- If you run **hb set** with no argument, the default setting process starts. 266 267- You can run **hb set -root** *dir* to set the root directory of the source code. 268 269- You can run **hb set -p** to set the product to build. 270 271**hb env** 272 273Displays current settings. 274 275```shell 276hb env 277[OHOS INFO] root path: xxx 278[OHOS INFO] board: hispark_taurus 279[OHOS INFO] kernel: liteos 280[OHOS INFO] product: ipcamera 281[OHOS INFO] product path: xxx/vendor/hisilicon/ipcamera 282[OHOS INFO] device path: xxx/device/hisilicon/hispark_taurus/sdk_linux_4.19 283``` 284 285**hb build** 286 287Builds a product, component, module, or chipset solution. 288 289```shell 290hb build -h 291usage: hb build [-h] [-b BUILD_TYPE] [-c COMPILER] [-t [TEST [TEST ...]]] [-cpu TARGET_CPU] [--dmverity] [--tee] 292 [-p PRODUCT] [-f] [-n] [-T [TARGET [TARGET ...]]] [-v] [-shs] [--patch] [--compact-mode] 293 [--gn-args GN_ARGS] [--keep-ninja-going] [--build-only-gn] [--log-level LOG_LEVEL] [--fast-rebuild] 294 [--device-type DEVICE_TYPE] [--build-variant BUILD_VARIANT] 295 [component [component ...]] 296 297positional arguments: 298 component name of the component, mini/small only 299 300optional arguments: 301 -h, --help show this help message and exit 302 -b BUILD_TYPE, --build_type BUILD_TYPE 303 release or debug version, mini/small only 304 -c COMPILER, --compiler COMPILER 305 specify compiler, mini/small only 306 -t [TEST [TEST ...]], --test [TEST [TEST ...]] 307 compile test suit 308 -cpu TARGET_CPU, --target-cpu TARGET_CPU 309 select cpu 310 --dmverity enable dmverity 311 --tee Enable tee 312 -p PRODUCT, --product PRODUCT 313 build a specified product with {product_name}@{company} 314 -f, --full full code compilation 315 -n, --ndk compile ndk 316 -T [TARGET [TARGET ...]], --target [TARGET [TARGET ...]] 317 compile single target 318 -v, --verbose show all command lines while building 319 -shs, --sign_haps_by_server 320 sign haps by server 321 --patch apply product patch before compiling 322 --compact-mode compatible with standard build system set to false if we use build.sh as build entrance 323 --gn-args GN_ARGS specifies gn build arguments, eg: --gn-args="foo="bar" enable=true blah=7" 324 --keep-ninja-going keeps ninja going until 1000000 jobs fail 325 --build-only-gn only do gn parse, do not run ninja 326 --log-level LOG_LEVEL 327 specifies the log level during compilationyou can select three levels: debug, info and error 328 --fast-rebuild it will skip prepare, preloader, gn_gen steps so we can enable it only when there is no change 329 for gn related script 330 --device-type DEVICE_TYPE 331 specifies device type 332 --build-variant BUILD_VARIANT 333 specifies device operating mode 334``` 335 336- If you run **hb build** with no argument, the previously configured code directory, product, and options are used for the build. The **-f** option deletes all products to be built. It is equivalent to running **hb clean** and **hb build**. 337 338- You can run **hb build** *{component_name}* to build product components separately based on the development board and kernel set for the product, for example, **hb build kv_store**. 339 340- You can run **hb build -p ipcamera@hisilicon** to skip the setting step and build the product directly. 341 342- You can run **hb build** in **device/board/device_company** to select the kernel and build an image that contains the kernel and drivers only based on the current development board and the selected kernel. 343 344**hb clean** 345 346Deletes all the files except **args.gn** and **build.log** in the **out** directory (default). To clear files in a specified directory, add the directory parameter to the command, for example, **hb clean out/board/product**. 347 348```shell 349hb clean 350usage: hb clean [-h] [out_path] 351 352positional arguments: 353 out_path clean a specified path. 354 355optional arguments: 356 -h, --help show this help message and exit 357``` 358 359> **NOTE** 360> 361> - For details about how to set up the build environment and perform the build, see the related topics in [Getting Started](../quick-start/quickstart-overview.md) 362> - OpenHarmony also provides the Docker environment, which spares the installation of the build tool. For details, see [Docker Environment](../get-code/gettools-acquire.md) 363 364### Building Procedures 365 366You can add and build a product, component, chipset solution, and module. For details, see: 367 368- [Adding and Building a Product](subsys-build-product.md#adding-and-building-a-product) 369- [Adding and Building a Component](subsys-build-component.md#adding-and-building-a-component) 370- [Adding and Building a Module](subsys-build-module.md#adding-and-building-a-module) 371- [Adding and Building a Chipset Solution](subsys-build-chip_solution.md#adding-and-building-a-chipset-solution) 372 373## FAQs 374 375- [Common Build Problems and Solutions](subsys-build-FAQ.md) 376 377## Reference 378 379- [deps and external_deps](subsys-build-reference.md#deps-and-external_deps) 380- [Using Sanitizer](subsys-build-reference.md#using-sanitizer) 381- [Information Collected by the Open Source Software Notice](subsys-build-reference.md#information-collected-by-the-open-source-software-notice) 382- [Parameters for Accelerating Local Build](subsys-build-reference.md#parameters-for-accelerating-local-build) 383- [Viewing Ninja Build Information](subsys-build-reference.md#viewing-ninja-build-information) 384 385
