[文章]OpenHarmony轻量和小型系统编译构建指导

概述
一个基于gn和ninja的构建系统，以支持OpenHarmony组件化开发为目标，提供以下基本功能：

• 支持按组件拼装产品并编译。
• 独立构建芯片解决方案厂商源码。
• 独立构建单个组件。
  

基本概念
在使用编译构建子系统前，应了解如下基本概念：

• 子系统
  子系统是一个逻辑概念，它由一个或多个具体的组件组成。OpenHarmony整体遵从分层设计，从下向上依次为：内核层、系统服务层、框架层和应用层。系统功能按照“系统 > 子系统 > 组件”逐级展开，在多设备部署场景下，支持根据实际需求裁剪某些非必要的子系统或组件。
• 组件
  系统最小的可复用、可配置、可裁剪的功能单元。组件具备目录独立可并行开发、可独立编译、可独立测试的特征。
• gn
  Generate ninja的缩写，用于产生ninja文件。
• ninja
  ninja是一个专注于速度的小型构建系统。
• hb
  OpenHarmony的命令行工具，用来执行编译命令。
  

目录结构
构建流程

编译构建流程如图1 所示，主要分设置和编译两步：
图 1  编译构建流程

• hb set: 设置OpenHarmony源码目录和要编译的产品。
• hb build: 编译产品、开发板或者组件。编译主要过程如下：
  
  • 读取编译配置：根据产品选择的开发板，读取开发板config.gni文件内容，主要包括编译工具链、编译链接命令和选项等。
  • 调用gn：调用gn gen命令，读取产品配置生成产品解决方案out目录和ninja文件。
  • 调用ninja：调用ninja -C out/board/product启动编译。
  • 系统镜像打包：将组件编译产物打包，设置文件属性和权限，制作文件系统镜像。
    

配置规则
为了实现芯片解决方案、产品解决方案与OpenHarmony是解耦的、可插拔的，组件、芯片解决方案和产品解决方案的路径、目录树和配置需遵循一定的规则，具体如下：
组件

组件源码路径命名规则为：{领域}/{子系统}/{组件}，组件目录树规则如下：

注意：组件的名称、源码路径、功能简介、是否必选、编译目标、RAM、ROM、编译输出、已适配的内核、可配置的特性和依赖等属性定义在build/lite/components目录下对应子系统的json文件中，新增组件时需要在对应子系统json文件中添加相应的组件定义。产品所配置的组件必须在某个子系统中被定义过，否则会校验失败。

以泛sensor子系统的sensor服务组件为例，组件属性定义描述文件字段说明如下：

组件BUILD.gn的编写建议如下：

• 编译目标名称与组件一致。
• 组件对外可配置的特性变量需声明在该组件BUILD.gn中，特性变量命名规则：ohos_{subsystem}_{component}_{feature}。特性在组件描述中也需要同步定义，在产品配置文件config.json中按需配置。
• 宏定义规则：OHOS_{SUBSYSTEM}_{COMPONENT}_{FEATURE}
  

  说明：组件的编译脚本语言为gn，gn的基本用法请见https://gn.googlesource.com/gn/+/master/docs/quick_start.md。 组件即为gn定义的编译目标，可以为静态库、动态库、可执行文件或group。
  

  
  

以图形的UI组件为例，foundation/graphic/ui/BUILD.gn文件如下：

芯片解决方案

• 芯片解决方案是指基于某款开发板的完整解决方案，包含驱动、设备侧接口适配、开发板sdk等。
• 芯片解决方案是一个特殊的组件，源码路径规则为：device/{芯片解决方案厂商}/{开发板}。
• 芯片解决方案组件会随产品选择的开发板默认编译。
  

芯片解决方案目录树规则如下：

说明：config.gni为开发板编译相关的配置，编译时会采用该配置文件中的参数编译所有OS组件，编译阶段系统全局可见。

config.gni的关键字段介绍如下：

产品解决方案产品解决方案为基于开发板的完整产品，主要包含产品对OS的适配、组件拼装配置、启动配置和文件系统配置等。产品解决方案的源码路径规则为：vendor/{产品解决方案厂商}/{产品名称}_。_产品解决方案也是一个特殊的组件。

产品解决方案的目录树规则如下：

注意：新增产品须按如上的规则创建目录和文件，编译构建系统将按该规则扫描已配置的产品。

关键的目录和文件详细介绍如下：

• vendor/company/product/init_configs/etc
  该文件夹中包含rcS脚本，Sxxx脚本和fstab脚本。init进程在启动系统服务之前执行这些脚本。执行的流程为“rcS->fstab->S00-xxx“。Sxxx脚本中的内容与开发板和产品需要有关，主要包括设备节点的创建、创建目录、扫描设备节点、修改文件权限等等。这些文件在产品编译的BUILD.gn中按需拷贝到产品out目录中，最终打包到rootfs镜像中。
• vendor/company/product/init_configs/init.cfg
  init进程启动服务的配置文件，当前支持解析的命令有：
  
  • start:  启动某个服务
  • mkdir: 创建文件夹
  • chmod: 修改指定路径/文件的权限
  • chown: 修改指定路径/文件的属组
  • mount: 挂载命令
    
  该文件中的各个字段的解释如下：
  

使用指导前提条件开发环境需安装gn、ninja构建工具、python 3.7.4及以上和hb。安装方法请见搭建系统基础环境。

hb工具使用说明hb是OpenHarmony的命令行工具，用来执行编译命令。以下对hb的常用命令进行说明。
hb set

• hb set 后无参数，进入默认设置流程
• hb set -root dir可直接设置代码根目录
• hb set -p设置要编译的产品
  

hb env
查看当前设置信息

hb build

• hb build后无参数，会按照设置好的代码路径、产品进行编译，编译选项使用与之前保持一致。-f 选项将删除当前产品所有编译产品，等同于hb clean + hb build.
• hb build {component_name}：基于设置好的产品对应的单板、内核，单独编译组件（e.g.：hb build kv_store)。
• hb build -p ipcamera@hisilicon：免set编译产品，该命令可以跳过set步骤，直接编译产品。
• 在device/device_company/board下单独执行hb build会进入内核选择界面，选择完成后会根据当前路径的单板、选择的内核编译出仅包含内核、驱动的镜像。
  

hb clean
清除out目录对应产品的编译产物，仅保留args.gn、build.log。清除指定路径可输入路径参数：hb clean out/board/product，默认将清除当前hb set的产品对应out路径。

新增组件
本小节介绍如何新增一个组件，首先确定组件归属的子系统和组件名称，然后按如下步骤新增：

• 源码开发完成后，添加组件编译脚本。
  以编译组件hello_world可执行文件为例，applications/sample/hello_world/BUILD.gn可以写为：
  

如上编译脚本，可编译出一个可在OpenHarmony上运行的名为hello_world的可执行文件。

单独编译该组件，hb set任意选择一款产品，然后使用-T选项单独编译组件：

• 编译产品。
  
  • 代码根目录输入hb set选择对应产品。
  • 执行hb build。
    

新增芯片解决方案

编译构建支持添加新的芯片解决方案厂商，具体步骤如下：

• 创建芯片解决方案目录。
  按照芯片解决方案配置规则创建目录，以芯片厂商realtek的“rtl8720“开发板为例, 在代码根目录执行：
  

• 编译芯片解决方案。
  在开发板目录下执行hb build，即可启动芯片解决方案的编译。
  

新增产品解决方案

编译构建支持芯片解决方案和组件的灵活拼装，形成定制化的产品解决方案。具体步骤如下：

• 创建产品目录
  按照产品解决方案配置规则创建产品目录，以基于“rtl8720“开发板的wifiiot模组为例，在代码根目录执行：
  

配置完成后，编译时增加–patch参数，即可在产品编译前将配置的Patch文件打到对应目录中，再进行编译：

• 编译产品。
  在代码根目录执行hb set按提示选择新增的产品，然后执行hb build即可启动编译。
  

常见问题编译构建过程中，提示“usr/sbin/ninja: invalid option – w”

• 现象描述：
  编译失败，提示“usr/sbin/ninja: invalid option – w”。
• 可能原因：
  编译环境中ninja版本太低，不支持–w选项。
• 解决办法：
  卸载环境中ninja和gn，按照获取工具。
  

编译构建过程中，提示“/usr/bin/ld: cannot find -lncurses”

• 现象描述：
  编译失败，提示“/usr/bin/ld: cannot find -lncurses”。
• 可能原因：
  编译环境ncurses库缺失。
• 解决办法：
  

编译构建过程中，提示“line 77: mcopy: command not found”

• 现象描述：
  ​编译失败，提示“line 77: mcopy: command not found”。
• 可能原因：
  编译环境未安装mcopy。
• 解决办法：
  

编译构建过程中，提示“riscv32-unknown-elf-gcc: error trying to exec ‘cc1’: execvp: No such file or directory”

• 现象描述：
  编译失败，提示“riscv32-unknown-elf-gcc: error trying to exec ‘cc1’: execvp: No such file or directory”。
• ​可能原因：
  当前用户对riscv编译器路径下的文件访问权限不够。
• ​解决办法：
  查询gcc_riscv32所在目录。
  

• 使用chmod命令修改目录权限为755。
  

编译构建过程中，提示“No module named ‘Crypto’”

• 现象描述：
  编译失败，提示“No module named ‘Crypto’”。
• 可能原因：
  python3未安装Crypto。
• 解决办法：
  
  • 查询Python版本号。
    

python3 --versionsudo pip3 install pycryptodome

• sudo pip3 install pycryptodome
  
  

编译构建过程中，提示“xx.sh : xx unexpected operator”

• 现象描述：
  编译失败：“xx.sh [: xx unexpected operator”。
• 可能原因：
  编译环境shell不是bash。
• 解决办法：