1# 编译构建指导 2 3## 概述 4 5OpenHarmony编译子系统是以GN和Ninja构建为基座，对构建和配置粒度进行部件化抽象、对内建模块进行功能增强、对业务模块进行功能扩展的系统，该系统提供以下基本功能： 6 7- 以部件为最小粒度拼装产品和独立编译。 8- 支持轻量、小型、标准三种系统的解决方案级版本构建，以及用于支撑应用开发者使用IDE开发的SDK开发套件的构建。 9- 支持芯片解决方案厂商的灵活定制和独立编译。 10 11### 适用范围 12 13本指导适用于轻量、小型、标准三种系统。[芯片解决方案配置规则](subsys-build-chip_solution.md#芯片解决方案配置规则)与[新增并编译芯片解决方案](subsys-build-chip_solution.md#新增并编译芯片解决方案)主要和轻量系统、小型系统相关，其他内容都是通用的。 14 15### 基本概念及包含关系 16 17 18在了解编译构建子系统的能力前，应了解如下基本概念： 19 20- 平台：开发板和内核的组合，不同平台支持的子系统和部件不同。 21- 产品：产品是包含一系列部件的集合，编译后产品的镜像包可以运行在不同的开发板上。 22- 子系统：OpenHarmony整体遵从分层设计，从下向上依次为：内核层、系统服务层、框架层和应用层（详见[OpenHarmony技术架构](https://gitee.com/openharmony#技术架构)）。系统功能按照“系统 > 子系统 > 部件”逐级展开，在多设备部署场景下，支持根据实际需求裁剪某些非必要的子系统或部件。子系统是一个逻辑概念，它具体由对应的部件构成。 23- 部件：对子系统的进一步拆分，可复用的软件单元，它包含源码、配置文件、资源文件和编译脚本；能独立构建，以二进制方式集成，具备独立验证能力的二进制单元。需要注意的是下文中的芯片解决方案本质是一种特殊的部件。 24- 模块：模块就是编译子系统的一个编译目标，部件也可以是编译目标。 25- 特性：特性是部件用于体现不同产品之间的差异。 26- GN：Generate Ninja的缩写，用于产生Ninja文件。 27- Ninja：Ninja是一个专注于速度的小型构建系统。 28- hb：OpenHarmony的命令行工具，用来执行编译命令。 29 30基于以上概念，编译子系统通过配置来实现编译和打包，该子系统主要包括：模块、部件、子系统、产品。 31 32**图1** 产品、子系统、部件和模块间关系 33 34 35 36图1体现了编译子系统的各部分关系，主要体现为： 37 38- 子系统是某个路径下所有部件的集合，一个部件只能属于一个子系统。 39- 部件是模块的集合，一个模块只能归属于一个部件。 40- 通过产品配置文件配置一个产品包含的部件列表，部件不同的产品配置可以复用。 41- 部件可以在不同的产品中实现有差异，通过变体或者特性feature实现。 42- 模块就是编译子系统的一个编译目标，部件也可以是编译目标。 43 44### 运作机制 45 46编译构建可以编译产品、部件和模块，但是不能编译子系统。编译构建流程如下图所示，主要分设置和编译两步： 47 48**图2** 编译构建流程 49 50 51 521. hb set: 设置要编译的产品。 53 542. hb build: 编译产品、开发板或者部件。编译主要过程如下： 55 56 1. 读取编译配置：根据产品选择的开发板，读取开发板config.gni文件内容，主要包括编译工具链、编译链接命令和选项等。 57 2. 调用GN：调用gn gen命令，读取产品配置生成产品解决方案out目录和Ninja文件。 58 3. 调用Ninja：调用ninja -C out/board/product启动编译。 59 4. 系统镜像打包：将部件编译产物打包，设置文件属性和权限，制作文件系统镜像。 60 61### 约束限制 62 63编译环境目前主要支持Ubuntu18.04和Ubuntu20.04（Ubuntu22.04暂不支持）。 64 65### 环境配置 66 67安装编译所需的程序包。 安装命令： 68 69- 安装方式一：使用脚本，在当前工程目录执行 70 ```shell 71 ./build/build_scripts/env_setup.sh 72 ``` 73 74- 安装方式二：apt-get和pip3 install命令安装 75 ```shell 76 apt-get update -y 77 apt-get install -y 78 # 如果是ubuntu20.04系统请直接安装python3.9，如果是ubuntu18.04请改为安装python3.8 79 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 80 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 81 apt-get install -y libxinerama-dev libxcursor-dev libxrandr-dev libxi-dev 82 # python需要安装以下模块，repo文件在上一章节约束与限制的源码获取中得到。 83 chmod +x /usr/bin/repo 84 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 85 pip3 install esdk-obs-python --trusted-host pypi.org 86 pip3 install six --upgrade --ignore-installed six 87 #还需要安装llvm，hc-gen，gcc_riscv32，Ninja，node-v14.15.4-linux-x64，GN，如果用户使用的shell环境不是bash或者zsh的配置，则需要配置以下环境变量： 88 # export PATH=/home/tools/llvm/bin:$PATH 89 # export PATH=/home/tools/hc-gen:$PATH 90 # export PATH=/home/tools/gcc_riscv32/bin:$PATH 91 # export PATH=/home/tools/ninja:$PATH 92 # export PATH=/home/tools/node-v12.20.0-linux-x64/bin:$PATH 93 # export PATH=/home/tools/gn:$PATH 94 # export PATH=~/.local/bin:$PATH 95 ``` 96 97 **注意**：上述安装ohos-build的过程中会安装编译工具hb，但有时会出现hb安装不成功的情况，若安装不成功，则按照[hb安装](../../device-dev/quick-start/quickstart-pkg-install-tool.md#安装hb)重新安装。 98 99 100## 配置规则 101 102为了实现芯片解决方案、产品解决方案与OpenHarmony是解耦的、可插拔的，子系统、产品、部件、芯片解决方案、模块、特性和系统能力需遵循一定的规则，具体配置规则见如下链接： 103 104- [产品配置规则](subsys-build-product.md#产品配置规则) 105- [子系统配置规则](subsys-build-subsystem.md#子系统配置规则) 106- [部件配置规则](subsys-build-component.md#部件配置规则) 107- [模块配置规则](subsys-build-module.md#模块配置规则) 108- [芯片解决方案配置规则](subsys-build-chip_solution.md#芯片解决方案配置规则) 109- [特性配置规则](subsys-build-feature.md#特性配置规则) 110- [系统能力配置规则](subsys-build-syscap.md#如何按需配置部件的系统能力) 111 112## 编译构建使用指导 113 114### 目录结构 115 116```shell 117 118/build # 编译构建主目录 119 120├── __pycache__ 121├── build_scripts/ # 编译相关的python脚本 122├── common/ 123├── config/ # 编译相关的配置项 124├── core 125│ ├── gn/ # 编译入口BUILD.gn配置 126 └── build_scripts/ 127├── docs 128gn_helpers.py* 129lite/ # hb和preloader入口 130misc/ 131├── ohos # OpenHarmony编译打包流程配置 132│ ├── kits # kits编译打包模板和处理流程 133│ ├── ndk # ndk模板和处理流程 134│ ├── notice # notice模板和处理流程 135│ ├── packages # 版本打包模板和处理流程 136│ ├── sa_profile # sa模板和处理流程 137│ ├── sdk # sdk模板和处理流程，包括sdk中包含的模块配置 138│ └── testfwk # 测试相关的处理 139├── ohos.gni* # 汇总了常用的gni文件，方便各个模块一次性import 140├── ohos_system.prop 141├── ohos_var.gni* 142├── prebuilts_download.sh* 143├── print_python_deps.py* 144├── scripts/ 145├── subsystem_config.json 146├── subsystem_config_example.json 147├── templates/ # c/c++编译模板定义 148├── test.gni* 149├── toolchain # 编译工具链配置 150├── tools # 常用工具 151├── version.gni 152├── zip.py* 153 154``` 155 156 157 158### 编译命令 159 160首先，在源码根目录下执行prebuilts脚本进行预编译，安装编译器及二进制工具。 161 162```shell 163bash build/prebuilts_download.sh 164``` 165 166接着，使用命令行方式或hb方式执行编译命令。 167 1681.命令行方式 169 170- 代码根目录下执行全量版本的编译命令： 171 172 Release版本 : 173 ```shell 174 ./build.sh --product-name {product_name} 175 ``` 176 Debug版本 : 177 ```shell 178 ./build.sh --product-name {product_name} --gn-args is_debug=true 179 ``` 180 >  **注意：** 181 > Debug全版本因镜像大小限制，全量编译可能无法烧录，建议单模块编译Debug二进制。使用如下命令单独编译模块： 182 > 183 > 184 > ``` 185 > ./build.sh --product-name {product_name} --gn-args is_debug=true --build-target {target_name} 186 > ``` 187 > 188 {product_name}为当前版本支持的平台。比如：hispark_taurus_standard等。 189 190 编译完成后，结果镜像保存在 out/{device_name}/packages/phone/images/ 目录下。 191 192 193 194- 编译命令支持选项：./build.sh 195 196 ```shell 197 -h, --help # 显示帮助信息并退出 198 --source-root-dir=SOURCE_ROOT_DIR # 指定路径 199 --product-name=PRODUCT_NAME # 指定产品名 200 --device-name=DEVICE_NAME # 指定装置名称 201 --target-cpu=TARGET_CPU # 指定CPU 202 --target-os=TARGET_OS # 指定操作系统 203 -T BUILD_TARGET, --build-target=BUILD_TARGET # 指定编译目标，可以指定多个 204 --gn-args=GN_ARGS # GN参数，支持指定多个 205 --ninja-args=NINJA_ARGS # Ninja参数，支持指定多个 206 -v, --verbose # 生成时显示所有命令行 207 --keep-ninja-going # 让Ninja持续到1000000个工作失败 208 --jobs=JOBS 209 --export-para=EXPORT_PARA 210 --build-only-gn # 只做GN解析，不运行Ninja 211 --ccache # 可选 如果使用ccache，需要本地安装ccache 212 --fast-rebuild # 快速重建，默认值为False 213 --log-level=LOG_LEVEL # 指定编译期间的日志级别'，'三个级别可选：debug, info and error，default='info' 214 --device-type=DEVICE_TYPE # 指定设备类型，默认值为'default' 215 --build-variant=BUILD_VARIANT # 指定设备操作模式，默认值为'user' 216 ``` 217 2182.hb方式 219 220hb是OpenHarmony的命令行工具，用来执行编译命令。以下对hb的常用命令进行说明。 221 222**hb set** 223 224设置要编译的产品 225 226```shell 227hb set -h 228usage: hb set [-h] [-root [ROOT_PATH]] [-p] 229 230optional arguments: 231 -h, --help show this help message and exit 232 -root [ROOT_PATH], --root_path [ROOT_PATH] 233 Set OHOS root path 234 -p, --product Set OHOS board and kernel 235``` 236 237- hb set 后无参数，进入默认设置流程 238 239- hb set -root dir可直接设置代码根目录 240 241- hb set -p设置要编译的产品 242 243**hb env** 244 245查看当前设置信息 246 247```shell 248hb env 249[OHOS INFO] root path: xxx 250[OHOS INFO] board: hispark_taurus 251[OHOS INFO] kernel: liteos 252[OHOS INFO] product: ipcamera 253[OHOS INFO] product path: xxx/vendor/hisilicon/ipcamera 254[OHOS INFO] device path: xxx/device/hisilicon/hispark_taurus/sdk_linux_4.19 255``` 256 257**hb build** 258 259编译产品、部件、模块或芯片解决方案。 260 261```shell 262hb build -h 263usage: hb build [-h] [-b BUILD_TYPE] [-c COMPILER] [-t [TEST [TEST ...]]] [-cpu TARGET_CPU] [--dmverity] [--tee] 264 [-p PRODUCT] [-f] [-n] [-T [TARGET [TARGET ...]]] [-v] [-shs] [--patch] [--compact-mode] 265 [--gn-args GN_ARGS] [--keep-ninja-going] [--build-only-gn] [--log-level LOG_LEVEL] [--fast-rebuild] 266 [--device-type DEVICE_TYPE] [--build-variant BUILD_VARIANT] 267 [component [component ...]] 268 269positional arguments: 270 component name of the component, mini/small only 271 272optional arguments: 273 -h, --help show this help message and exit 274 -b BUILD_TYPE, --build_type BUILD_TYPE 275 release or debug version, mini/small only 276 -c COMPILER, --compiler COMPILER 277 specify compiler, mini/small only 278 -t [TEST [TEST ...]], --test [TEST [TEST ...]] 279 compile test suit 280 -cpu TARGET_CPU, --target-cpu TARGET_CPU 281 select cpu 282 --dmverity enable dmverity 283 --tee Enable tee 284 -p PRODUCT, --product PRODUCT 285 build a specified product with {product_name}@{company} 286 -f, --full full code compilation 287 -n, --ndk compile ndk 288 -T [TARGET [TARGET ...]], --target [TARGET [TARGET ...]] 289 compile single target 290 -v, --verbose show all command lines while building 291 -shs, --sign_haps_by_server 292 sign haps by server 293 --patch apply product patch before compiling 294 --compact-mode compatible with standard build system set to false if we use build.sh as build entrance 295 --gn-args GN_ARGS specifies gn build arguments, eg: --gn-args="foo="bar" enable=true blah=7" 296 --keep-ninja-going keeps ninja going until 1000000 jobs fail 297 --build-only-gn only do gn parse, do not run ninja 298 --log-level LOG_LEVEL 299 specifies the log level during compilationyou can select three levels: debug, info and error 300 --fast-rebuild it will skip prepare, preloader, gn_gen steps so we can enable it only when there is no change 301 for gn related script 302 --device-type DEVICE_TYPE 303 specifies device type 304 --build-variant BUILD_VARIANT 305 specifies device operating mode 306``` 307 308- hb build后无参数，会按照设置好的代码路径、产品进行编译，编译选项使用与之前保持一致。-f 选项将删除当前产品所有编译产品，等同于hb clean + hb build. 309 310- hb build {component_name}：基于设置好的产品对应的单板、内核，单独编译部件（e.g.：hb build kv_store)。 311 312- hb build -p ipcamera@hisilicon：免set编译产品，该命令可以跳过set步骤，直接编译产品。 313 314- 在device/board/device_company下单独执行hb build会进入内核选择界面，选择完成后会根据当前路径的单板、选择的内核编译出仅包含内核、驱动的镜像。 315 316**hb clean** 317 318清除out目录对应产品的编译产物，仅保留args.gn、build.log。清除指定路径可输入路径参数：hb clean out/board/product，默认将清除当前hb set的产品对应out路径。 319 320```shell 321hb clean 322usage: hb clean [-h] [out_path] 323 324positional arguments: 325 out_path clean a specified path. 326 327optional arguments: 328 -h, --help show this help message and exit 329``` 330 331>  **说明：** 332> - 设备开发过程中详细的编译环境搭建及编译步骤请参考[快速入门中的环境搭建及编译章节。](../quick-start/quickstart-overview.md) 333> - OpenHarmony还为开发者提供了Docker编译环境，可以省略编译工具的安装，具体使用请参考[Docker编译指导。](../get-code/gettools-acquire.md) 334 335### 新增并编译不同配置 336 337根据上一节的配置规则新增相应配置并进行编译，主要包含产品、部件、芯片解决方案和模块四个粒度。具体如下： 338 339- [新增并编译产品](subsys-build-product.md#新增并编译产品) 340- [新增并编译部件](subsys-build-component.md#新增并编译部件) 341- [新增并编译模块](subsys-build-module.md#新增并编译模块) 342- [新增并编译芯片解决方案](subsys-build-chip_solution.md#新增并编译芯片解决方案) 343 344## 常见问题 345 346- [常见编译问题和解决方法](subsys-build-FAQ.md#常见编译问题和解决方法) 347 348## 参考信息 349 350- [关于deps、external_deps的使用](subsys-build-reference.md#关于deps、external_deps的使用) 351- [Sanitizer使用说明](subsys-build-reference.md#Sanitizer使用说明) 352- [开源软件Notice收集策略说明](subsys-build-reference.md#开源软件notice收集策略说明) 353- [加快本地编译的一些参数](subsys-build-reference.md#加快本地编译的一些参数) 354- [查看NinjaTrace](subsys-build-reference.md#查看ninjatrace) 355 356
