1# HAP编译构建指导
2
3## 概述
4此指导用于在OpenHarmony中通过gn实现完整应用的编译、签名和镜像安装。
5### 基本概念
6| 术语 | 含义 |
7| -------------- | ---------------------- |
8| HAP            | OpenHarmony Ability Package，一个HAP文件包含应用的所有内容，由代码、资源、三方库及应用配置文件组成，其文件后缀名为.hap。 |
9| APP            | OpenHarmony Application Package, 一个APP文件包含多个Hap，文件后缀名为.app。 |
10| Ability        | 应用的重要组成部分，是应用所具备能力的抽象。Ability是系统调度应用的最小单元，是能够完成一个独立功能的组件，一个应用可以包含一个或多个Ability。 |
11| FA             | Feature Ability，是FA模型的Ability框架下具有UI界面的Ability类型，用于与用户进行交互。Feature Ability唯一对应一种模板，即Page模板（Page Ability）。 |
12| PA             | Particle Ability，是在FA模型的Ability框架下无界面的Ability，主要为Feature Ability提供服务与支持，例如作为后台服务提供计算能力，或作为数据仓库提供数据访问能力。Particle Ability有三种模板，分别为Service模板（Service Ability）、Data模板（Data Ability）、以及Form模板（Form Ability）。 |
13| FA模型         | 两种Ability框架模型结构的其中一种。是Ability框架在API 8及更早版本采用FA模型。FA模型将Ability分为FA（Feature Ability）和PA（Particle Ability）两种类型，其中FA支持Page Ability模板，PA支持Service ability、Data ability、以及Form ability模板。详情可参考[FA模型综述](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/application-models/fa-model-development-overview.md)。 |
14| Stage模型 | 两种Ability框架模型结构的其中一种。从API 9开始支持。Stage模型将Ability分为Ability和ExtensionAbility两大类，其中ExtensionAbility又被扩展为ServiceExtensionAbility、FormExtensionAbility、DataShareExtensionAbility等等一系列ExtensionAbility。详情可参考[Stage模型综述](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/application-models/stage-model-development-overview.md)。 |
15
16### 功能简介
17提供HAP和APP编译功能
18
19## 开发指导
20
21### 编译系统提供的模板
22#### ohos_app
23
24声明一个APP目标，该目标会生成一个或多个HAP，最终将会打包到system镜像中。
25
26| 支持的变量 | 说明 |
27| --------- | ---- |
28| **hap_name** | 指定输出hap的名称，仅用于应用工程中只包含单个hap的场景，默认值为"${target_name}" |
29| **build_profile** | 默认为build-profile.json5 |
30| **system_lib_deps** | 依赖的系统库 |
31| **module_libs_dir** | 所依赖的系统库在应用中的目录，与**system_lib_deps**共同使用，默认为"entry" |
32| **deps** | 当前目标的依赖 |
33| **subsystem_name** | (required) APP从属的子系统名，需要和ohos.build中的名字对应，否则将导致无法安装到system镜像中。|
34| **part_name** | (required) APP从属的部件名，同subsystem_name。|
35| **module_install_dir** | 安装到system中的位置，默认安装在system/app目录下。|
36| **js_build_mode** | 可选，用于配置HAP是“release”还是“debug”模型编译，默认“release”。|
37| **install_enable** | 是否安装到镜像，默认为true |
38| **hap_out_dir** | 单个应用中所有hap的输出目录，默认为"${target_out_dir}/${target_name}" |
39| **test_hap** | 对应用中的HAP测试ohosTest进行编译, 默认为false |
40| **test_module** | 编译的测试用例ohosTest所在的模块名，与**test_hap**共同使用，默认为entry |
41| **sdk_home** | 用于指定sdk的所在路径, 默认为"//prebuilts/ohos-sdk/linux" |
42| **sdk_type_name** | 用于指定sdk类型, 默认为["sdk.dir"] |
43| **build_level** | 用于指定应用的编译级别，默认为"project", 可以指定为"module" |
44| **assemble_type** | 用于指定应用产物类型，默认为"AssembleApp", 可以指定为"AssembleHap" |
45
46
47
48### 操作步骤
49
501. 将开发完成的应用example放到应用归档目录下，例如目录"applications/standard"。
51
522. 配置gn脚本applications/standard/example/BUILD.gn，简单示例如下：
53   ```
54   import("//build/ohos.gni") # 引用ohos.gni
55
56   ohos_app("example") {
57     part_name = "prebuilt_hap"   # 必选
58     subsystem_name = "applications"  # 必选
59     certificate_profile = "./signature/example.p7b"  # 必选
60     system_lib_deps = [ "//applications/standard/MyApplication8/telephony_data:tel_telephony_data_test" ] # 依赖系统库，需要时添加
61     module_libs_dir = "entry"  # 使用system_lib_deps时指定
62   }
63   ```
64
653. 修改applications/standard/hap/ohos.build，示例如下：
66   ```
67   {
68     "subsystem": "applications",
69     "parts": {
70       "prebuilt_hap": {
71         "module_list": [
72           ...
73           "//applications/standard/example:example" # 添加编译目标
74         ]
75       }
76     }
77   }
78   ```
79
804. 编译命令：
81   ```
82   # 全量编译
83   ./build.sh --product-name {product_name}
84
85   # 单独编译APP
86   ./build.sh --product-name {product_name} --build-target applications/standard/example:example
87   ```
88
895. 编译产物，简单例子HAP解压视图如下：
90   ```
91   .
92   ├── ets
93   │   ├── entryability
94   │   │   └── EntryAbility.abc
95   │   └── pages
96   │       └── Index.abc
97   ├── libs
98   │   └── armeabi-v7a
99   │       ├── libc++_shared.so
100   │       ├── libentry.so
101   │       └── libtel_telephony_data_test.z.so
102   ├── module.json
103   ├── pack.info
104   ├── resources
105   │   └── base
106   │       ├── media
107   │       │   ├── app_icon.png
108   │       │   └── icon.png
109   │       └── profile
110   │           └── main_pages.json
111   └── resources.index
112   ```
113
114### 注意事项：
1151. xts应用须使用ohos_js_app_suite模板，该模板是对ohos_app的封装，支持参数与ohos_app相同，差异点在于**hap_out_dir**默认在"out/{product_name}/suites/{xts_type}/testcases/"下。模板使用示例如下：
116   ```
117   import("//test/xts/tool/build/suite.gni")
118
119   ohos_js_app_suite("test_example") {
120     hap_name = "test_example"
121     testonly = true
122     certificate_profile = "./signatrue/test_example.p7b"
123     subsystem_name = "common"
124     part_name = subsystem_name
125   }
126   ```
127
1282. 如果使用应用提供的ohosTest测试Hap编译功能，需要单独创建测试hap的目标并使能test_hap字段，同时指定对应的test_module, 例如：
129   ```
130   import("//build/ohos.gni")
131
132   ohos_hap("example") {
133    hap_name = "example"
134    certificate_profile = "./signatrue/example.p7b"
135    subsystem_name = "common"
136    part_name = subsystem_name
137   }
138
139   ohos_hap("test_example") {
140    hap_name = "test_example"
141    certificate_profile = "./signatrue/example.p7b"
142    test_hap = true
143    test_module = "entry"
144    subsystem_name = "common"
145    part_name = subsystem_name
146   }
147   ```
148   上面的模板将会编译出example.hap和test_example.hap，其中test_example.hap是由entry/ohosTest中的源码编译产生。
149