149 lines
7.1 KiB
Markdown
149 lines
7.1 KiB
Markdown
# HAP编译构建指导
|
||
|
||
## 概述
|
||
此指导用于在OpenHarmony中通过gn实现完整应用的编译、签名和镜像安装。
|
||
### 基本概念
|
||
| 术语 | 含义 |
|
||
| -------------- | ---------------------- |
|
||
| HAP | OpenHarmony Ability Package，一个HAP文件包含应用的所有内容，由代码、资源、三方库及应用配置文件组成，其文件后缀名为.hap。 |
|
||
| APP | OpenHarmony Application Package, 一个APP文件包含多个Hap，文件后缀名为.app。 |
|
||
| Ability | 应用的重要组成部分，是应用所具备能力的抽象。Ability是系统调度应用的最小单元，是能够完成一个独立功能的组件，一个应用可以包含一个或多个Ability。 |
|
||
| FA | Feature Ability，是FA模型的Ability框架下具有UI界面的Ability类型，用于与用户进行交互。Feature Ability唯一对应一种模板，即Page模板（Page Ability）。 |
|
||
| PA | Particle Ability，是在FA模型的Ability框架下无界面的Ability，主要为Feature Ability提供服务与支持，例如作为后台服务提供计算能力，或作为数据仓库提供数据访问能力。Particle Ability有三种模板，分别为Service模板（Service Ability）、Data模板（Data Ability）、以及Form模板（Form Ability）。 |
|
||
| 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)。 |
|
||
| 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)。 |
|
||
|
||
### 功能简介
|
||
提供HAP和APP编译功能
|
||
|
||
## 开发指导
|
||
|
||
### 编译系统提供的模板
|
||
#### ohos_app
|
||
|
||
声明一个APP目标，该目标会生成一个或多个HAP，最终将会打包到system镜像中。
|
||
|
||
| 支持的变量 | 说明 |
|
||
| --------- | ---- |
|
||
| **hap_name** | 指定输出hap的名称，仅用于应用工程中只包含单个hap的场景，默认值为"${target_name}" |
|
||
| **build_profile** | 默认为build-profile.json5 |
|
||
| **system_lib_deps** | 依赖的系统库 |
|
||
| **module_libs_dir** | 所依赖的系统库在应用中的目录，与**system_lib_deps**共同使用，默认为"entry" |
|
||
| **deps** | 当前目标的依赖 |
|
||
| **subsystem_name** | (required) APP从属的子系统名，需要和ohos.build中的名字对应，否则将导致无法安装到system镜像中。|
|
||
| **part_name** | (required) APP从属的部件名，同subsystem_name。|
|
||
| **module_install_dir** | 安装到system中的位置，默认安装在system/app目录下。|
|
||
| **js_build_mode** | 可选，用于配置HAP是“release”还是“debug”模型编译，默认“release”。|
|
||
| **install_enable** | 是否安装到镜像，默认为true |
|
||
| **hap_out_dir** | 单个应用中所有hap的输出目录，默认为"${target_out_dir}/${target_name}" |
|
||
| **test_hap** | 对应用中的HAP测试ohosTest进行编译, 默认为false |
|
||
| **test_module** | 编译的测试用例ohosTest所在的模块名，与**test_hap**共同使用，默认为entry |
|
||
| **sdk_home** | 用于指定sdk的所在路径, 默认为"//prebuilts/ohos-sdk/linux" |
|
||
| **sdk_type_name** | 用于指定sdk类型, 默认为["sdk.dir"] |
|
||
| **build_level** | 用于指定应用的编译级别，默认为"project", 可以指定为"module" |
|
||
| **assemble_type** | 用于指定应用产物类型，默认为"AssembleApp", 可以指定为"AssembleHap" |
|
||
|
||
|
||
|
||
### 操作步骤
|
||
|
||
1. 将开发完成的应用example放到应用归档目录下，例如目录"applications/standard"。
|
||
|
||
2. 配置gn脚本applications/standard/example/BUILD.gn，简单示例如下：
|
||
```
|
||
import("//build/ohos.gni") # 引用ohos.gni
|
||
|
||
ohos_app("example") {
|
||
part_name = "prebuilt_hap" # 必选
|
||
subsystem_name = "applications" # 必选
|
||
certificate_profile = "./signature/example.p7b" # 必选
|
||
system_lib_deps = [ "//applications/standard/MyApplication8/telephony_data:tel_telephony_data_test" ] # 依赖系统库，需要时添加
|
||
module_libs_dir = "entry" # 使用system_lib_deps时指定
|
||
}
|
||
```
|
||
|
||
3. 修改applications/standard/hap/ohos.build，示例如下：
|
||
```
|
||
{
|
||
"subsystem": "applications",
|
||
"parts": {
|
||
"prebuilt_hap": {
|
||
"module_list": [
|
||
...
|
||
"//applications/standard/example:example" # 添加编译目标
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
4. 编译命令：
|
||
```
|
||
# 全量编译
|
||
./build.sh --product-name {product_name}
|
||
|
||
# 单独编译APP
|
||
./build.sh --product-name {product_name} --build-target applications/standard/example:example
|
||
```
|
||
|
||
5. 编译产物，简单例子HAP解压视图如下：
|
||
```
|
||
.
|
||
├── ets
|
||
│ ├── entryability
|
||
│ │ └── EntryAbility.abc
|
||
│ └── pages
|
||
│ └── Index.abc
|
||
├── libs
|
||
│ └── armeabi-v7a
|
||
│ ├── libc++_shared.so
|
||
│ ├── libentry.so
|
||
│ └── libtel_telephony_data_test.z.so
|
||
├── module.json
|
||
├── pack.info
|
||
├── resources
|
||
│ └── base
|
||
│ ├── media
|
||
│ │ ├── app_icon.png
|
||
│ │ └── icon.png
|
||
│ └── profile
|
||
│ └── main_pages.json
|
||
└── resources.index
|
||
```
|
||
|
||
### 注意事项：
|
||
1. xts应用须使用ohos_js_app_suite模板，该模板是对ohos_app的封装，支持参数与ohos_app相同，差异点在于**hap_out_dir**默认在"out/{product_name}/suites/{xts_type}/testcases/"下。模板使用示例如下：
|
||
```
|
||
import("//test/xts/tool/build/suite.gni")
|
||
|
||
ohos_js_app_suite("test_example") {
|
||
hap_name = "test_example"
|
||
testonly = true
|
||
certificate_profile = "./signatrue/test_example.p7b"
|
||
subsystem_name = "common"
|
||
part_name = subsystem_name
|
||
}
|
||
```
|
||
|
||
2. 如果使用应用提供的ohosTest测试Hap编译功能，需要单独创建测试hap的目标并使能test_hap字段，同时指定对应的test_module, 例如：
|
||
```
|
||
import("//build/ohos.gni")
|
||
|
||
ohos_hap("example") {
|
||
hap_name = "example"
|
||
certificate_profile = "./signatrue/example.p7b"
|
||
subsystem_name = "common"
|
||
part_name = subsystem_name
|
||
}
|
||
|
||
ohos_hap("test_example") {
|
||
hap_name = "test_example"
|
||
certificate_profile = "./signatrue/example.p7b"
|
||
test_hap = true
|
||
test_module = "entry"
|
||
subsystem_name = "common"
|
||
part_name = subsystem_name
|
||
}
|
||
```
|
||
上面的模板将会编译出example.hap和test_example.hap，其中test_example.hap是由entry/ohosTest中的源码编译产生。
|