README.md
1# Compilation and Building \(for Mini and Small Systems\)<a name="EN-US_TOPIC_0000001130006475"></a>
2
3- [Introduction](#section11660541593)
4- [Directory Structure](#section161941989596)
5- [Usage](#section1312121216216)
6 - [Usage Guidelines](#section129654513264)
7
8- [Repositories Involved](#section1371113476307)
9
10## Introduction<a name="section11660541593"></a>
11
12The compilation and building subsystem is a build framework based on Generate Ninja \(GN\) and Ninja, which supports component-based OpenHarmony development. This subsystem can be used to:
13
14- Build products.
15
16- Build chipset vendor components independently.
17- Build a single component independently.
18
19It is considered best practice to learn the following basic concepts before you start development and build:
20
21- **Component**
22
23 A component is a reusable software unit that can contain source code, configuration files, resource files, and build scripts.
24
25- **GN**
26
27 GN is short for Generate Ninja, which is a build system used to generate Ninja files.
28
29- **Ninja**
30
31 Ninja is a small high-speed build system.
32
33
34**Build Process**
35
36The following figure shows the build process.
37
38**Figure 1** Build process<a name="fig1531311552204"></a>
39
40
411. **hb set**: Set the OpenHarmony source code directory and the product to build.
422. **hb build**: Build the product, development board, or component. The process to build the solution is as follows:
43 - **Reading configuration**: Read the development board configuration, which covers the toolchain, linking commands, and build options.
44 - **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.
45 - **Running Ninja**: Run **ninja -C out/company/product** to start build.
46 - **Packaging**: Package the build result to create a file system image.
47
48
49## Directory Structure<a name="section161941989596"></a>
50
51```
52build/lite # Primary directory
53├── components # Component description file
54├── hb # hb pip installation package
55├── make_rootfs # make script for the file system
56├── config # Build configuration items
57│ ├── component # Definitions of component-related templates, including static libraries, dynamic libraries, extension components, and emulator libraries
58│ ├── kernel # Build configuration parameters of the kernel
59│ └── subsystem # Subsystem template
60├── ndk # NDK-related build scripts and configuration parameters
61└── toolchain # Build toolchain, which contain the compiler directories, build options, and linking options
62```
63
64## Usage<a name="section1312121216216"></a>
65
66### Usage Guidelines<a name="section129654513264"></a>
67
681. **Prerequisites**
69 - Server and OS version: Linux server running 64-bit Ubuntu 16.04 or later
70 - Python version: 3.7.4 or later
71 - Repository: **build\_lite** of OpenHarmony source code
72
732. **Installing hb**
74 - Run the following command in the root directory of the source code:
75
76 ```
77 python3 -m pip install --user build/lite
78 ```
79
80 - Run the **hb -h** command. If the following information is displayed, the installation is successful:
81
82 ```
83 usage: hb
84
85 OHOS build system
86
87 positional arguments:
88 {build,set,env,clean}
89 build Build source code
90 set OHOS build settings
91 env Show OHOS build env
92 clean Clean output
93
94 optional arguments:
95 -h, --help Show this help message and exit
96 ```
97
98 - **Uninstalling hb**
99
100 Run the following command to uninstall hb:
101
102 ```
103 python3 -m pip uninstall ohos-build
104 ```
105
106
1073. **Build Commands**
108 1. **hb set**
109
110 ```
111 hb set -h
112 usage: hb set [-h] [-root [ROOT_PATH]] [-p]
113
114 optional arguments:
115 -h, --help Show this help message and exit.
116 -root [ROOT_PATH], --root_path [ROOT_PATH]
117 Set OHOS root path.
118 -p, --product Set OHOS board and kernel.
119 ```
120
121 - If you run **hb set** with no argument, the default setting process starts.
122 - You can run **hb set -root** _\[ROOT\_PATH\]_ to set the root directory of the source code.
123 - **hb set -p --product** is used to set the product to build.
124
125 2. **hb env**
126
127 View the current configuration.
128
129 ```
130 hb env
131 [OHOS INFO] root path: xxx
132 [OHOS INFO] board: hispark_taurus
133 [OHOS INFO] kernel: liteos
134 [OHOS INFO] product: ipcamera
135 [OHOS INFO] product path: xxx/vendor/hisilicon/ipcamera
136 [OHOS INFO] device path: xxx/device/hisilicon/hispark_taurus/sdk_linux_4.19
137 ```
138
139 3. **hb build**
140
141 ```
142 hb build -h
143 usage: hb build [-h] [-b BUILD_TYPE] [-c COMPILER] [-t [TEST [TEST ...]]]
144 [--dmverity] [-p PRODUCT] [-f] [-n]
145 [component [component ...]]
146
147 positional arguments:
148 component Name of the component.
149
150 optional arguments:
151 -h, --help Show this help message and exit.
152 -b BUILD_TYPE, --build_type BUILD_TYPE
153 Release or debug version.
154 -c COMPILER, --compiler COMPILER
155 Specify compiler.
156 -t [TEST [TEST ...]], --test [TEST [TEST ...]]
157 Compile test suit.
158 --dmverity Enable dmverity.
159 -p PRODUCT, --product PRODUCT
160 Build a specified product with
161 {product_name}@{company}, eg: ipcamera@hisilcon.
162 -f, --full Full code compilation.
163 -T [TARGET [TARGET ...]], --target [TARGET [TARGET ...]]
164 Compile single target
165 ```
166
167 - If you run **hb build** with no argument, the previously configured code directory, product, and options are used for build.
168 - 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**.
169 - You can run **hb build -p PRODUCT** to skip the setting step and build the product directly.
170 - 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.
171
172 4. **hb clean**
173
174 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_.
175
176 ```
177 hb clean
178 usage: hb clean [-h] [out_path]
179
180 positional arguments:
181 out_path Clean a specified path.
182
183 optional arguments:
184 -h, --help Show this help message and exit.
185 ```
186
187
188
189## Repositories Involved<a name="section1371113476307"></a>
190
191Compilation and building subsystem
192
193**[build\_lite](https://gitee.com/openharmony/build_lite)**
README_zh.md
1# 轻量级编译构建组件<a name="ZH-CN_TOPIC_0000001130006475"></a>
2
3- [简介](#section11660541593)
4- [目录](#section161941989596)
5- [说明](#section1312121216216)
6 - [使用说明](#section129654513264)
7
8- [相关仓](#section1371113476307)
9
10## 简介<a name="section11660541593"></a>
11
12一个基于gn和ninja的支持OpenHarmony组件化开发的编译框架，主要提供以下功能：
13
14- 构建产品。
15
16- 独立构建芯片厂商组件。
17- 独立构建单个组件。
18
19在开发编译构建前，应了解如下基本概念：
20
21- 组件
22
23 可复用的软件单元，它可包含源码、配置文件、资源文件和编译脚本等。
24
25- gn
26
27 Generate ninja的缩写，一种元构建系统，用于产生ninja文件。
28
29- ninja
30
31 ninja是一个专注于速度的小型构建系统。
32
33
34构建流程如下：
35
36编译构建流程如图1所示，主要包括设置和编译两步：
37
38**图 1** 编译构建流程<a name="fig1531311552204"></a>
39
40
411. hb set: 设置OpenHarmony源码目录和要编译的产品。
422. hb build: 编译产品、开发板或者组件。解决方案编译实现如下：
43 - 读取开发板配置：主要包括开发板使用的编译工具链、编译链接命令和选项等。
44 - 调用gn: 调用gn gen命令，读取产品配置\(主要包括开发板、内核、选择的组件等\)生成解决方案out目录和ninja文件。
45 - 调用ninja：调用ninja -C out/company/product启动编译。
46 - 系统镜像打包：将组件编译产物打包，制作文件系统镜像。
47
48
49## 目录<a name="section161941989596"></a>
50
51```
52build/lite # 编译构建主目录
53├── components # 组件描述文件。
54├── hb # hb pip安装包源码。
55├── make_rootfs # 文件系统制作脚本。
56├── config # 编译相关的配置项
57│ ├── component # 组件相关的模板定义。包括：静态库、动态库、扩展组件、模拟器库等
58│ ├── kernel # 内核的编译配置参数
59│ └── subsystem # 子系统模板
60├── ndk # Native API相关编译脚本与配置参数
61└── toolchain # 编译工具链相关，包括：编译器路径、编译选项、链接选项等。
62```
63
64## 说明<a name="section1312121216216"></a>
65
66### 使用说明<a name="section129654513264"></a>
67
681. **前提条件**
69 - Linux服务器，Ubuntu16.04及以上64位系统版本。
70 - Python 3.7.4及以上。
71 - OpenHarmony源码build\_lite仓下载成功。
72
732. **安装hb**
74 - 在源码根目录下执行：
75
76 ```
77 python3 -m pip install --user build/lite
78 ```
79
80 - 执行hb -h有相关帮助信息，有打印信息即表示安装成功：
81
82 ```
83 usage: hb
84
85 OHOS build system
86
87 positional arguments:
88 {build,set,env,clean}
89 build Build source code
90 set OHOS build settings
91 env Show OHOS build env
92 clean Clean output
93
94 optional arguments:
95 -h, --help show this help message and exit
96 ```
97
98 - 卸载方法：
99
100 ```
101 python3 -m pip uninstall ohos-build
102 ```
103
104
1053. **编译命令**
106 1. **hb set**
107
108 ```
109 hb set -h
110 usage: hb set [-h] [-root [ROOT_PATH]] [-p]
111
112 optional arguments:
113 -h, --help Show this help message and exit.
114 -root [ROOT_PATH], --root_path [ROOT_PATH]
115 Set OHOS root path.
116 -p, --product Set OHOS board and kernel.
117 ```
118
119 - hb set 后无参数，进入默认设置流程
120 - hb set -root \[ROOT\_PATH\] 直接设置代码根目录
121 - hb set -p --product 设置要编译的产品
122
123 2. **hb env**
124
125 查看当前设置信息
126
127 ```
128 hb env
129 [OHOS INFO] root path: xxx
130 [OHOS INFO] board: hispark_taurus
131 [OHOS INFO] kernel: liteos
132 [OHOS INFO] product: ipcamera
133 [OHOS INFO] product path: xxx/vendor/hisilicon/ipcamera
134 [OHOS INFO] device path: xxx/device/hisilicon/hispark_taurus/sdk_linux_4.19
135 ```
136
137 3. **hb build**
138
139 ```
140 hb build -h
141 usage: hb build [-h] [-b BUILD_TYPE] [-c COMPILER] [-t [TEST [TEST ...]]]
142 [--dmverity] [-p PRODUCT] [-f] [-n]
143 [component [component ...]]
144
145 positional arguments:
146 component Name of the component.
147
148 optional arguments:
149 -h, --help Show this help message and exit.
150 -b BUILD_TYPE, --build_type BUILD_TYPE
151 Release or debug version.
152 -c COMPILER, --compiler COMPILER
153 Specify compiler.
154 -t [TEST [TEST ...]], --test [TEST [TEST ...]]
155 Compile test suit.
156 --dmverity Enable dmverity.
157 -p PRODUCT, --product PRODUCT
158 Build a specified product with
159 {product_name}@{company}, eg: ipcamera@hisilcon.
160 -f, --full Full code compilation.
161 -T [TARGET [TARGET ...]], --target [TARGET [TARGET ...]]
162 Compile single target
163 ```
164
165 - hb build后无参数，会按照设置好的代码路径、产品进行编译，编译选项使用与之前保持一致。
166 - hb build component：基于设置好的产品对应的单板、内核，单独编译组件（e.g.：hb build kv\_store\)。
167 - hb build -p PRODUCT：免set编译产品，该命令可以跳过set步骤，直接编译产品。
168 - 在device/device\_company/board下单独执行hb build会进入内核选择界面，选择完成后会根据当前路径的单板、选择的内核编译出仅包含内核、驱动的镜像。
169
170 4. **hb clean**
171
172 清除out目录对应产品的编译产物，仅剩下args.gn、build.log。清除指定路径可输入路径参数：hb clean xxx/out/xxx，否则将清除hb set的产品对应out路径
173
174 ```
175 hb clean
176 usage: hb clean [-h] [out_path]
177
178 positional arguments:
179 out_path Clean a specified path.
180
181 optional arguments:
182 -h, --help Show this help message and exit.
183 ```
184
185
186
187## 相关仓<a name="section1371113476307"></a>
188
189**[编译构建子系统](https://gitee.com/openharmony/docs/blob/master/zh-cn/readme/编译构建子系统.md)**
190
191**[build](https://gitee.com/openharmony/build/blob/master/README_zh.md)**
