@toc

Guide

这是一篇讲解如何在OpenHarmony标准系统的代码仓里正确添加自己的代码文章，包含对OpenHarmony分布式代码结构的理解和子系统、组件/部件以及特性概念的理解，以及如何增加自己的组件或特性。供OpenHarmony开发爱好者参考。

一、概述

OpenHarmony开源代码的组成部分如下：

OpenHarmony标准系统的各个产品或者产品形态均是由多个子系统组成，子系统又有多个组件（也叫部件，后面统一称为组件）组成，而组件是有多个特性组成，特性是最小的集合，三者的大小关系为：子系统>组件>特性；
通过对各组成部分的不同配置达到产品可定制化的目的。目前OpenHarmony共支持二十多个子系统，对于后续的开发一般不需要新增子系统，只需要通过新增组件或者特性的方式完成需求的开发，下面是新增组件和特性的指导方法。

二、如何新增组件

1.配置组件，使组件参加编译

step 1、 在产品配置文件中添加组件的编译入口

在productdefine/common/products/ 目录下，找到对应的产品名字的配置文件，这里以产品Hi3516DV300的配置文件Hi3516DV300.json为例，在parts中添加组件的编译入口，格式为：“所属子系统名:组件名”:{}。组件名自己定义，但要跟下面的保持一致。示例如下：

step 2、 在所属子系统的配置文件ohos.build/bundle.json中添加组件的编译入口

1、在build/subsystem_config.json文件中可以查阅各子系统的根目录，根目录下或者根目录的子目录下会有一个或多个ohos.build文件，均是改子系统的配置文件。一个子系统可以配置多个组件。
一个组件一般包含module_list、inner_kits、system_kits、test_list四个部分的声明：
- module_list：组件包含的模块列表，必选
- inner_kits：组件提供其它组件的接口（和跨组件模块依赖external_deps相对应）
- system_kits：组件提供给生成应用的接口
- test_list：组件对应模块的测试用例
在原有子系统中添加一个新的组件，有两种方法，一种是在该子系统原有的ohos.build文件中添加该组件，另一种是新建一个ohos.build文件，注意无论哪种方式该ohos.build文件均在对应子系统所在文件夹下。
示例如下：
这里采用的是该子系统原有的ohos.build文件中添加。

格式为：新增特性源码编译入口脚本BUILD.gn的路径：该BUILD.gn内编译的入口（该格式后面统称为编译入口）

注意：
a、组件的特性，要添加在组件配置的module_list中，或者可以被module_list中的模块依赖到；
b、组件要加到对应产品的组件列表中；
c、ohos.build文件包含两个部分，第一部分subsystem说明了子系统的名称，第二部分parts说明了该子系统包含的所有组件。要添加一个组件，需要把该组件对应的内容添加进parts中去：添加的时候需要指明该组件的名字（即示例中和上文保持一致的my_part组件），组件包含的模块module_list，假如有提供给其它组件的接口，需要在inner_kits中添加，假如有测试用例，需要在test_list中说明，inner_kits与test_list没有也可以不添加。

2、目前OpenHarmony-3.1-Release引入了bundle.json，和ohos.build是相互兼容的，二者均可以添加组件的编译入口。示例如下:

预计bundle.json会逐渐替换掉ohos.build。

2.增加特性，即参与编译的源码

2.1 在特性目录下编写BUILD.gn，根据类型选择对应的模板。

组件是由特性组成，特性要指定part_name，指定它归属的组件，一个特性只能属于一个组件。
示例如下：
在 base/update下新增一个归属于my_part组件的特性：新建文件夹my_component、源码my_test.c和脚本BUILD.gn，截图如下：


注意：这里的BUILD.gn的路径和其内部的入口要和第二章节的step 2中module_list里配置的保持一致，否则编译关系匹配不到。
OpenHarmony模板请参考附1

2.2 查看示例编译结果

编译命令为：./build.sh --product-name Hi3516DV300 --ccache
也可以单组编译组件：./build.sh --product-name Hi3516DV300 --build-target my_part
在编译启动后，编译系统会解析配置文件，生成产品的全部的组件列表，输出为：
out/{产品名}/build_configs/parts_info/parts_info.json。
示例如下：

新增特性生成的目标文件如下：

附1：OpenHarmony的gn模板介绍

OpenHarmony源码编译系统使用了google开发的gn工具以及ninjia。这二者结合起来比传统的makefile编译系要高效，尤其适合大系统的并行编译。对开发者而言，如果要参与OpenHarmony的开发，需要对gn的语法有些了解。
本文仅做一些最基本的介绍：
a. 使用gn工具的话，开发者将编译规则写在名为BUILD.gn文件中。和Makefile一样，gn文件有自己的语法规则，属于领域语言（Domain Specific Language，DSL）。gn语法不难，但编译规则本身有很多内容，所以一下子要掌握全部内容也不容易。
b. gn支持自定义模板函数，可放在名为.gni的文件中。OpenHarmony中最常见到的gn模板文件见目录./build/templates。.gn文件中通过import可导入gni模板文件。
OpenHarmony标准系统当前支持的模板类型如下：
ohos_executable \\ 可执行文件
ohos_shared_library \\一个.dll或的.so
ohos_static_library \\静态库
ohos_source_set
预编译模板如下：
ohos_prebuilt_executable \\拷贝可执行文件
ohos_prebuilt_shared_library \\拷贝so文件
ohos_prebuilt_etc \\拷贝其他格式的文件
在模块目录下配置BUILD.gn，根据类型选择对应的模板。可以使用提供的模板，也可以使用gn语法规则自定义编写。
例子：ohos_shared_library示例：

import("//build/ohos.gni")
ohos_shared_library("helloworld") {
  sources = []
  include_dirs = []
  cflags = []
  cflags_c = []
  cflags_cc = []
  ldflags = []
  configs = []
  deps =[]  # 组件内模块依赖，可选

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

  output_name = "" # 可选，模块输出名
  output_extension = "" # 可选，模块名后缀
  module_install_dir = "" #可选，缺省在/system/lib64或/system/lib下， 模块安装路径，模块安装路径，从system/，vendor/后开始指定
  relative_install_dir = "" #可选，模块安装相对路径，相对于/system/lib64或/system/lib；如果有module_install_dir配置时，该配置不生效
  install_images = [] # 可选，缺省值system，指定模块安装到那个分区镜像中，可以指定多个
  part_name = "" # 必选，所属组件名称
}

ohos_executable示例：
ohos_executable模板属性和ohos_shared_library基本一致，请参考ohos_shared_library的例子。
注意：可执行模块（即ohos_executable模板定义的）默认是不安装的，如果要安装，需要指定install_enable = true
ohos_prebuilt_etc示例：

import("//build/ohos.gni")
ohos_prebuilt_etc("etc_file") {
  source = "file"
  deps = []  # 组件内模块依赖
  module_install_dir = "" #可选，模块安装路径，从system/，vendor/后开始指定
  relative_install_dir = "" #可选，模块安装相对路径，相对于system/etc；如果有module_install_dir配置时，该配置不生效
  part_name = "" # 必选，所属组件名称
}