Files
phs_v1.0.1.0/build/docs/how-to-build-a-hap.md
2024-09-27 19:16:49 +08:00

334 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# HAP编译构建指导
## 概述
### 基本概念
| 术语 | 含义 |
| -------------- | ---------------------- |
| HAP | OpenHarmony Ability Package一个HAP文件包含应用的所有内容由代码、资源、三方库及应用配置文件组成其文件后缀名为.hap。 |
| 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分为FAFeature Ability和PAParticle 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编译构建功能支持FA模型、Stage模型。
## 开发指导
### 编译系统提供的模板
#### ohos_hap
声明一个HAP目标该目标会生成一个HAP最终将会打包到system镜像中。
| 支持的变量 | 说明 |
| --------- | ---- |
| hap_profile | HAP的config.jsonStage模型对应module.json。 |
| raw_assets | 原始assets这些assets会直接拷贝到HAP的assets目录下。 |
| resources | 资源文件编译后放置在assets/entry/resources目录下 |
| js_assets | js资源ace编译后放置在assets/js/default目录下。|
| ets_assets | ets资源ace编译后放置在assets/js/default目录下 |
| deps | 当前目标的依赖 |
| shared_libraries | 当前目标依赖的native库 |
| hap_name | HAP的名字可选默认为目标名 |
| final_hap_path | 用户可以制定生成的HAP的位置可选final_hap_path中会覆盖hap_name。|
| subsystem_name | HAP从属的子系统名需要和ohos.build中的名字对应否则将导致无法安装到system镜像中。|
| part_name | HAP从属的部件名同subsystem_name。|
| js2abc | 是否需要将该HAP的js代码转换为ARK的字节码。|
| ets2abc | 是否需要将该HAP的ets代码转换为ARK的字节码。|
| certificate_profile | HAP对应的授权文件用于签名。|
| certificate_file | 证书文件证书文件和授权文件应用开发者需要去openharmony官网申请。|
| keystore_path | keystore文件用于签名。|
| keystore_password | keystore的密码用于签名。|
| key_alias | key的别名。|
| module_install_name | 安装时的HAP名称。|
| module_install_dir | 安装到system中的位置默认安装在system/app目录下。|
| js_build_mode | 可选用于配置HAP是“release”还是“debug”模型编译默认“release”。|
#### ohos_app_scope
声明一个HAP的AppScope模块该目标的app_profile和sources会在编译时拼接到具体的entry内编译该模板只在Stage模型下使用。
| 支持的变量 | 说明 |
| --------- | ---- |
| app_profile | HAP的AppScope中的app.json。|
| sources | HAP的AppScope中的资源resources。|
#### ohos_js_assets
js或ets代码ace编译后放置在assets/js/default目录下stage模型根据代码分别放置到js或ets目录。
| 支持的变量 | 说明 |
| --------- | ---- |
| hap_profile | HAP的config.json仅FA模型下配置。|
| source_dir | js或ets代码路径兼容FA模型的单ability配置到ability目录。|
| ets2abc | 当前为ets代码卡片应用必须配置其他应用可在ohos_hap中配置无需重复配置。|
| js2abc | 当前为js代码卡片应用必须配置其他应用可在ohos_hap中配置无需重复配置。|
#### ohos_assets
原始assets这些assets会直接拷贝到HAP的assets目录下。
| 支持的变量 | 说明 |
|---------- | ---- |
| sources | 原始assets的路径。|
#### ohos_resources
资源文件FA模型编译后放置在assets/entry/resources目录下Stage模型编译后放置在resources目录下。
| 支持的变量 | 说明 |
| --------- | ---- |
| hap_profile | HAP的config.jsonStage模型对应module.json。|
| sources | 资源文件路径。|
| deps | 当前目标的依赖。Stage模型需要配置对ohos_app_scope目标的依赖。|
### 操作步骤
1. 将开发完成的应用example放到applications/standard/目录下。
2. 配置gn脚本applications/standard/example/BUILD.gnFA模型简单示例如下更多BUILD.gn配置见[gn脚本配置示例](#gn脚本配置示例)
```
import("//build/ohos.gni") # 引用ohos.gni
ohos_hap("example") {
hap_profile = "./src/main/config.json" # config.json
js_assets = ["./src/main/js/default"]
raw_assets = ["./raw_assets"]
resources = ["./src/main/resources"]
shared_libraries = [
"//third_party/libpng:libpng", # native库
]
certificate_profile = "../signature/systemui.p7b" # Cer文件
hap_name = "SystemUI-NavigationBar" # 名字
part_name = "prebuilt_hap"
subsystem_name = "applications"
}
```
3. 修改applications/standard/hap/ohos.build示例如下
```
{
"subsystem": "applications",
"parts": {
"prebuilt_hap": {
"module_list": [
...
"//applications/standard/example:example" # 添加编译目标
]
}
}
}
```
4. 编译命令:
```
# 全量编译
./build.sh --product-name {product_name}
# 单独编译HAP
./build.sh --product-name {product_name} --build-target applications/standard/example:example
```
5. 编译产物FA模型简单例子HAP解压视图如下
```
Length Date Time Name
--------- ---------- ----- ----
1439 2009-01-01 00:00 assets/raw_assets -----> raw_assets
354 2009-01-01 00:00 assets/entry/resources.index ------> resources
1 2009-01-01 00:00 assets/entry/resources/base/media/attributes.key ------> resources
1 2009-01-01 00:00 assets/entry/resources/base/media/constants.key ------> resources
1 2009-01-01 00:00 assets/entry/resources/base/media/contents.key ------> resources
6790 2009-01-01 00:00 assets/entry/resources/base/media/icon.png ------> resources
1 2009-01-01 00:00 assets/entry/resources/base/media/nodes.key ------> resources
11170 2009-01-01 00:00 assets/js/default/app.js ------> js_assets
48 2009-01-01 00:00 assets/js/default/i18n/en-US.json ------> js_assets
50 2009-01-01 00:00 assets/js/default/i18n/zh-CN.json ------> js_assets
224 2009-01-01 00:00 assets/js/default/manifest.json ------> js_assets
41481 2009-01-01 00:00 assets/js/default/pages/index/index.js ------> js_assets
909 2009-01-01 00:00 config.json ------> hap_profile
266248 2009-01-01 00:00 libs/libpng.z.so ------> shared_libraries
```
### gn脚本配置示例
- FA模型多ability示例
```
import("//build/ohos.gni")
ohos_hap("dataability") {
hap_profile = "entry/src/main/config.json"
deps = [
":dataability_js_assets",
":dataability_resources",
]
certificate_profile = "signature/openharmony_sx.p7b"
hap_name = "dataability"
part_name = "prebuilt_hap"
subsystem_name = "applications"
}
ohos_js_assets("dataability_js_assets") {
ets2abc = true
source_dir = "entry/src/main/ets"
hap_profile = "entry/src/main/config.json"
}
ohos_resources("dataability_resources") {
sources = [
"entry/src/main/resources",
]
hap_profile = "entry/src/main/config.json"
}
```
- FA模型Js卡片示例
```
import("//build/ohos.gni")
ohos_hap("FormOfFaJs") {
hap_profile = "entry/src/main/config.json"
deps = [
":FormOfFaJs_js_assets",
":FormOfFaJs_resources",
]
certificate_profile = "signature/openharmony_sx.p7b"
hap_name = "FormOfFaJs"
part_name = "prebuilt_hap"
subsystem_name = "applications"
}
ohos_js_assets("FormOfFaJs_js_assets") {
hap_profile = "entry/src/main/config.json"
js2abc = true
source_dir = "entry/src/main/js"
}
ohos_resources("FormOfFaJs_resources") {
sources = [
"entry/src/main/resources",
]
hap_profile = "entry/src/main/config.json"
}
```
- FA模型Ets卡片示例
```
import("//build/ohos.gni")
ohos_hap("FormOfFaEts") {
hap_profile = "entry/src/main/config.json"
deps = [
":FormOfFaEts_js_assets",
":FormOfFaEts_form_js_assets",
":FormOfFaEts_resources",
]
certificate_profile = "signature/openharmony_sx.p7b"
hap_name = "FormOfFaEts"
part_name = "prebuilt_hap"
subsystem_name = "applications"
}
ohos_js_assets("FormOfFaEts_js_assets") {
hap_profile = "entry/src/main/config.json"
ets2abc = true
source_dir = "entry/src/main/ets"
}
ohos_js_assets("FormOfFaEts_form_js_assets") {
hap_profile = "entry/src/main/config.json"
js2abc = true
source_dir = "entry/src/main/js"
}
ohos_resources("FormOfFaEts_resources") {
sources = [
"entry/src/main/resources",
]
hap_profile = "entry/src/main/config.json"
}
```
- Stage模型简单示例
```
import("//build/ohos.gni")
ohos_hap("actmoduletest") {
hap_profile = "entry/src/main/module.json"
deps = [
":actmoduletest_js_assets",
":actmoduletest_resources",
]
certificate_profile = "signature/openharmony_sx.p7b"
hap_name = "actmoduletest"
part_name = "prebuilt_hap"
subsystem_name = "applications"
}
ohos_app_scope("actmoduletest_app_profile") {
app_profile = "AppScope/app.json"
sources = [ "AppScope/resources" ]
}
ohos_js_assets("actmoduletest_js_assets") {
ets2abc = true
source_dir = "entry/src/main/ets"
}
ohos_resources("actmoduletest_resources") {
sources = [
"entry/src/main/resources",
]
deps = [
":actmoduletest_app_profile",
]
hap_profile = "entry/src/main/module.json"
}
```
- Stage模型卡片示例
```
import("//build/ohos.gni")
ohos_hap("FormOfStageEts") {
hap_profile = "entry/src/main/module.json"
deps = [
":FormOfStageEts_js_assets",
":FormOfStageEts_form_js_assets",
":FormOfStageEts_resources",
]
js_build_mode = "debug" # 默认release
certificate_profile = "signature/openharmony_sx.p7b"
hap_name = "FormOfStageEts"
part_name = "prebuilt_hap"
subsystem_name = "applications"
}
ohos_js_assets("FormOfStageEts_js_assets") {
ets2abc = true
source_dir = "entry/src/main/ets"
}
ohos_js_assets("FormOfStageEts_form_js_assets") {
js2abc = true
source_dir = "entry/src/main/js"
}
ohos_app_scope("FormOfStageEts_app_profile") {
app_profile = "AppScope/app.json"
sources = [ "AppScope/resources" ]
}
ohos_resources("FormOfStageEts_resources") {
sources = [
"entry/src/main/resources",
]
deps = [
":FormOfStageEts_app_profile",
]
hap_profile = "entry/src/main/module.json"
}
```