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模型综述。
Stage模型	两种Ability框架模型结构的其中一种。从API 9开始支持。Stage模型将Ability分为Ability和ExtensionAbility两大类，其中ExtensionAbility又被扩展为ServiceExtensionAbility、FormExtensionAbility、DataShareExtensionAbility等等一系列ExtensionAbility。详情可参考Stage模型综述。

功能简介

提供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中的源码编译产生。