【本文正在参加2023年第一期优质创作者激励计划计】

子系统，部件，模块编译构建全实践

个人简介：深圳技术大学FSR实验室大三学生，正于九联科技实习，共同学习研究鸿蒙南向开发知识。
博客主页：https://ost.51cto.com/person/posts/15624680

@[toc]

前言

大家好，前段时间学业比较忙，已经有挺长一段时间没有更新博客了，这段时间开始实习生活，会将更多的精力投入到开源鸿蒙的研究学习中，会尽量多更新实习期间的所学所得，分享给大家，一起学习进步！
本篇文章要分享的是OpenHarmony的一个编译构建实践，随着版本更新，OpenHarmony的编译方式也会出现一些小变化，这次将以OpenHarmony-3.2-Beta版本为例，使用九联UnionPi-Tiger开发板，介绍下子系统，部件，模块的配置规则以及编译构建实践。

概述

OpenHarmony整体遵从分层设计，从下向上依次为：内核层、系统服务层、框架层和应用层。系统功能按照“系统 > 子系统 > 部件”逐级展开，在多设备部署场景下，支持根据实际需求裁剪某些非必要的子系统或部件。

• 子系统：子系统是一个逻辑概念，它具体由对应的部件构成。

• 部件：对子系统的进一步拆分，可复用的软件单元，它包含源码、配置文件、资源文件和编译脚本；能独立构建，以二进制方式集成，具备独立验证能力的二进制单元。需要注意的是下文中的芯片解决方案本质是一种特殊的部件。

• 模块：模块就是编译子系统的一个编译目标，部件也可以是编译目标。

• 特性（feature）：特性是部件用于体现不同产品之间的差异。
  

上图编译子系统的各部分关系，主要体现为：

• 子系统是某个路径下所有部件的集合，一个部件只能属于一个子系统。
• 部件是模块的集合，一个模块只能归属于一个部件。
• 通过产品配置文件配置一个产品包含的部件列表，部件不同的产品配置可以复用。
• 部件可以在不同的产品中实现有差异，通过变体或者特性feature实现。
• 模块就是编译子系统的一个编译目标，部件也可以是编译目标。

环境

• OpenHarmony-3.2-Beta5
• 九联UnionPi-Tiger开发板
• USB_Burning_Tool烧录工具
• 串口调试助手

参考

编译构建指导
NAPI框架生成代码集成到OpenHarmony的方法

一. 子系统配置

通过build仓下的subsystem\_config.json可以查看所有子系统的配置规则。子系统的配置规则主要是在build/subsystem_config.json中指定子系统的路径和子系统名称。

注意：在已有子系统的目录下再创建子系统会导致重复获取到部件配置文件而导致报错。（血泪教训）

二. 部件配置

bundle.json与ohos.build

配置完子系统后，系统会自动识别该目录下的所有部件配置文件，新增部件的方式有两种，分别为增加ohos.build文件方式和增加bundle.json文件方式，各自的配置方法如下。

1. ohos.build配置格式

{
    "subsystem": "mysubsys"					# mysubsys所属子系统的名字
    "parts": {
        "ohos_build_test": {					# ohos_build_test为部件名称
            "module_list": [
                "//mysubsys/ohos_build_test:mygroup"		# 部件编译入口
            ]
            "test_list": []
        }
    }
}

2. bundle.json配置格式

{
    "name": "@ohos/sensor_lite",		                                 # HPM部件英文名称，格式"@组织/部件名称"
    "description": "Sensor services",		                             # 部件功能一句话描述	
    "version": "3.1",			                                         # 版本号，版本号与OpenHarmony版本号一致
    "license": "MIT",			                                         # 部件License
    "publishAs": "code-segment",		                                 # HPM包的发布方式，当前默认都为code-segment
    "segment": {										
        "destPath": ""			
    },					                                                 # 发布类型为code-segment时为必填项，定义发布类型code-segment的代码还原路径（源码路径）			
    "dirs": {"base/sensors/sensor_lite"},	                             # HPM包的目录结构，字段必填内容可以留空
    "scripts": {},			                                             # HPM包定义需要执行的脚本，字段必填，值非必填
    "licensePath": "COPYING",			
    "readmePath": {
        "en": "README.rst"
    },
    "component": {			                                             # 部件属性
        "name": "sensor_lite",			                                 # 部件名称		
        "subsystem": "",		                                         # 部件所属子系统
        "syscap": [],				                                     # 部件为应用提供的系统能力
        "features": [],                                                  # 部件对外的可配置特性列表，一般与build中的sub_component对应，可供产品配置
        "adapted_system_type": [],		                                 # 轻量(mini)小型(small)和标准(standard)，可以是多个
        "rom": "92KB",                                                   # 部件ROM值
        "ram": "~200KB",                                                 # 部件RAM估值       
        "deps": {                      
        "components": [                                                  # 部件依赖的其他部件
          "samgr_lite",
          "ipc_lite"
        ],
        "third_party": [                                                 # 部件依赖的三方开源软件
          "bounds_checking_function"
        ]
      }         
        "build": {				                                         # 编译相关配置
            "sub_component": [
                ""//base/sensors/sensor_lite/services:sensor_service"",  # 部件编译入口
            ],			                                                 # 部件编译入口，模块在此处配置
            "inner_kits": [],						                     # 部件间接口
            "test": []							                         # 部件测试用例编译入口
        }
    }
 }

• 部件配置中需要配置部件的名称、源码路径、功能简介、是否必选、编译目标、RAM、ROM、编译输出、已适配的内核、可配置的特性和依赖等属性定义。

使用场景对比

两种集成方式使用场景说明：
ohos.build方式集成：适合3.0前版本使用。
bundle.json方式集成：兼容ohos.build方式，但3.1及以后版本建议使用此种方式集成，更好兼容HPM。

三. 模块配置

具体参考模块配置规则。
编译子系统通过模块、部件和产品三层配置来实现编译和打包。模块就是编译子系统的一个目标，包括（动态库、静态库、配置文件、预编译模块等）。模块要定义属于哪个部件，一个模块只能归属于一个部件。OpenHarmony使用定制化的Gn模板来配置模块规则。
以下是常用的模块配置规则：

# C/C++模板
ohos_shared_library
ohos_static_library
ohos_executable
ohos_source_set

# 预编译模板：
ohos_prebuilt_executable
ohos_prebuilt_shared_library
ohos_prebuilt_static_library

#hap模板
ohos_hap
ohos_app_scope
ohos_js_assets
ohos_resources

#其他常用模板
#配置文件
ohos_prebuilt_etc

#sa配置
ohos_sa_profile

ohos开头的模板对应的.gni文件路径在：openharmony/build/templates/cxx/cxx.gni。
这里以ohos_executable为例，配置规则如下：

import("//build/ohos.gni")
ohos_executable("helloworld") {
  configs = []                       # 配置  
  part_name = [string]               # 部件名称 
  subsystem_name = [string]          # 子系统名称
  deps = []                          # 部件内模块依赖

  external_deps = [                  # 跨部件模块依赖定义，
  "part_name:module_name",           # 定义格式为 "部件名:模块名称"
  ]                                  # 这里依赖的模块必须是依赖的部件声明在inner_kits中的模块
  ohos_test = []
  test_output_dir = []

  # Sanitizer配置，每项都是可选的，默认为false/空
  sanitize = {
    # 各个Sanitizer开关
    cfi = [boolean]               # 控制流完整性检测
    cfi_cross_dso = [boolean]     # 开启跨so调用的控制流完整性检测
    integer_overflow = [boolean]  # 整数溢出检测
    boundary_sanitize = [boolean] # 边界检测
    ubsan = [boolean]             # 部分ubsan选项
    all_ubsan = [boolean]         # 全量ubsan选项
    ...

    debug = [boolean]             # 调测模式
    blocklist = [string]          # 屏蔽名单路径
  }

  testonly = [boolean]
  license_as_sources = []
  license_file = []                  # 后缀名是.txt的文件
  remove_configs = []
  static_link = []
  install_images = []
  module_install_dir = []            # 模块安装路径，从system/，vendor/后开始指定
  relative_install_dir = []
  symlink_target_name = []
  output_dir = [directory]           # 存放输出文件的目录
  install_enable = [boolean]
  version_script = []
  use_exceptions = []
}

四. 编译构建全实践

1. 添加子系统mysubsys

在子系统下新建一个属于自己的名为mysubsys子系统，并在源码下建立相应的mysubsys目录。

  "mysubsys": {
    "path": "mysubsys",
    "name": "mysubsys"
  }

在mysubsys新建两个部件，分别用来测试bundle.json以及ohos.build配置部件的实现结果。注意ohos.build或者bundle.json文件均在对应子系统所在文件夹下，BUILD.gn文件位置可以根据需要指定，整体目录结构如下：

mysubsys
├── bundle_json_test
│   ├── BUILD.gn
│   ├── bundle.json
│   └── test
│       ├── BUILD.gn
│       └── test.c
└── ohos_build_test
    ├── BUILD.gn
    ├── ohos.build
    └── test
        ├── BUILD.gn
        └── test.c

2. 为子系统配置部件及模块

2. 1 添加ohos.build测试部件及模块

mysubsys下新建一个ohos.build文件，根据ohos.build配置规则进行配置。同目录下建立BUILD.gn编译脚本，用于指定部件下模块编译入口，然后新建文件夹test作为测试模块，里面在新建test.c源文件以及BUILD.gn文件，生成可执行文件安装到开发板bin目录下，可执行文件名为mysubsys_test_ohos。编译构建关系如下图所示：

用于测试的源文件test.c:

#include "stdio.h"

int main()
{
    printf("test mysubsys for ohos.build\r\n");
    return 0;
}

2.2 添加bundle.json测试部件及模块

mysubsys下新建一个bundle.json文件，根据obundle.json配置规则进行配置。同目录下建立BUILD.gn编译脚本，用于指定部件下模块编译入口，然后新建文件夹test作为测试模块，里面在新建test.c源文件以及BUILD.gn文件，生成可执行文件安装到开发板bin目录下,可执行文件名为mysubsys_test_bundle。编译构建关系如下图所示：

#include "stdio.h"

int main()
{
    printf("test mysubsys for bundle.json\r\n");
    return 0;
}

上述两个实例可以直接在"module_list"或者"sub_component"里面直接将编译入口设置为你的模块目标（动态库、静态库、配置文件、预编译模块等），不过在学习过程中，发现OpenHarmony源码里面关于部件模块的写法（例如third_party），发现很多都会额外写一个BUILD.gn来新建一个group，用来包含一个或多个目标的虚节点，这里我也习惯这么写了。

3. 产品配置中添加相应子系统及部件

在vendor/unionman/unionpi_tiger/config.json文件添加如下配置：

4. 编译烧录运行

操作流程具体参考https://gitee.com/openharmony/device_board_unionman/blob/master/unionpi_tiger/README_zh.md，这里不多赘述。

./build.sh --product-name unionpi_tiger    #编译
./device/board/unionman/unionpi_tiger/common/tools/packer-unionpi.sh # 镜像打包

电脑连接开发板debug口，打开串口工具，生成的可执行文件mysubsys_test_ohos，mysubsys_test_bundle都可以在bin目录找到，在终端执行执行：

mysubsys_test_ohos
mysubsys_test_bundle

结果：