1# HAP编译构建指导 2 3## 概述 4 5### 基本概念 6| 术语 | 含义 | 7| -------------- | ---------------------- | 8| HAP | OpenHarmony Ability Package，一个HAP文件包含应用的所有内容，由代码、资源、三方库及应用配置文件组成，其文件后缀名为.hap。 | 9| Ability | 应用的重要组成部分，是应用所具备能力的抽象。Ability是系统调度应用的最小单元，是能够完成一个独立功能的组件，一个应用可以包含一个或多个Ability。 | 10| FA | Feature Ability，是FA模型的Ability框架下具有UI界面的Ability类型，用于与用户进行交互。Feature Ability唯一对应一种模板，即Page模板（Page Ability）。 | 11| PA | Particle Ability，是在FA模型的Ability框架下无界面的Ability，主要为Feature Ability提供服务与支持，例如作为后台服务提供计算能力，或作为数据仓库提供数据访问能力。Particle Ability有三种模板，分别为Service模板（Service Ability）、Data模板（Data Ability）、以及Form模板（Form Ability）。 | 12| 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模型综述](../../application-dev/ability/fa-brief.md)。 | 13| Stage模型 | 两种Ability框架模型结构的其中一种。从API 9开始支持。Stage模型将Ability分为Ability和ExtensionAbility两大类，其中ExtensionAbility又被扩展为ServiceExtensionAbility、FormExtensionAbility、DataShareExtensionAbility等等一系列ExtensionAbility。 | 14 15### 功能简介 16提供HAP编译构建功能，支持FA模型、Stage模型。 17 18## 开发指导 19 20### 编译子系统提供的模板 21#### ohos_hap 22 23声明一个HAP目标，该目标会生成一个HAP，最终将会打包到system镜像中。 24 25| 支持的变量 | 说明 | 26| --------- | ---- | 27| hap_profile | HAP的config.json，Stage模型对应module.json。 | 28| raw_assets | 原始assets，这些assets会直接拷贝到HAP的assets目录下。 | 29| resources | 资源文件，编译后放置在assets/entry/resources目录下 | 30| js_assets | js资源，ace编译后放置在assets/js/default目录下。| 31| ets_assets | ets资源，ace编译后放置在assets/js/default目录下 | 32| deps | 当前目标的依赖 | 33| shared_libraries | 当前目标依赖的native库 | 34| hap_name | HAP的名字，可选，默认为目标名 | 35| final_hap_path | 用户可以制定生成的HAP的位置，可选，final_hap_path中会覆盖hap_name。| 36| subsystem_name | HAP从属的子系统名，需要和ohos.build中的名字对应，否则将导致无法安装到system镜像中。| 37| part_name | HAP从属的部件名，同subsystem_name。| 38| js2abc | 是否需要将该HAP的js代码转换为ARK的字节码。| 39| ets2abc | 是否需要将该HAP的ets代码转换为ARK的字节码。| 40| certificate_profile | HAP对应的授权文件，用于签名。| 41| certificate_file | 证书文件，证书文件和授权文件，应用开发者需要去OpenHarmony官网申请。| 42| keystore_path | keystore文件，用于签名。| 43| keystore_password | keystore的密码，用于签名。| 44| key_alias | key的别名。| 45| module_install_name | 安装时的HAP名称。| 46| module_install_dir | 安装到system中的位置，默认安装在system/app目录下。| 47| js_build_mode | 可选，用于配置HAP是“release”还是“debug”模型编译，默认“release”。| 48 49#### ohos_app_scope 50声明一个HAP的AppScope模块，该目标的app_profile和sources会在编译时拼接到具体的entry内编译，该模板只在Stage模型下使用。 51 52| 支持的变量 | 说明 | 53| --------- | ---- | 54| app_profile | HAP的AppScope中的app.json，只在Stage模型下使用。| 55| sources | HAP的AppScope中的资源resources，只在Stage模型下使用。| 56 57#### ohos_js_assets 58js或ets代码，ace编译后放置在assets/js/default目录下，stage模型根据代码分别放置到js或ets目录。 59 60| 支持的变量 | 说明 | 61| --------- | ---- | 62| hap_profile | HAP的config.json，Stage模型对应module.json。| 63| source_dir | js或ets代码路径，兼容FA模型的单ability配置到ability目录。| 64| ets2abc | 当前为ets代码，主要用于卡片配置，其他应用可不配，使用ohos_hap中的配置。| 65| js2abc | 当前为js代码，主要用于卡片配置，其他应用可不配，使用ohos_hap中的配置。| 66 67#### ohos_assets 68原始assets，这些assets会直接拷贝到HAP的assets目录下。 69 70| 支持的变量 | 说明 | 71|---------- | ---- | 72| sources | 原始assets的路径。| 73 74#### ohos_resources 75资源文件，FA模型编译后放置在assets/entry/resources目录下，Stage模型编译后放置在resources目录下。 76 77| 支持的变量 | 说明 | 78| --------- | ---- | 79| hap_profile | HAP的config.json，Stage模型对应module.json。| 80| sources | 资源文件路径。| 81| deps | 当前目标的依赖。Stage模型需要配置对ohos_app_scope目标的依赖。| 82 83### 操作步骤 84 851. 将开发完成的应用example放到applications/standard/目录下。 86 872. 配置gn脚本applications/standard/example/BUILD.gn，FA模型简单示例如下（更多BUILD.gn配置见[gn脚本配置示例](#gn脚本配置示例)）： 88 ``` 89 import("//build/ohos.gni") # 引用ohos.gni 90 91 ohos_hap("example") { 92 hap_profile = "./src/main/config.json" # config.json 93 js_assets = ["./src/main/js/default"] 94 raw_assets = ["./raw_assets"] 95 resources = ["./src/main/resources"] 96 shared_libraries = [ 97 "//third_party/libpng:libpng", # native库 98 ] 99 certificate_profile = "../signature/systemui.p7b" # Cer文件 100 hap_name = "SystemUI-NavigationBar" # 名字 101 part_name = "prebuilt_hap" 102 subsystem_name = "applications" 103 } 104 ``` 105 1063. 修改applications/standard/hap/ohos.build，示例如下： 107 ``` 108 { 109 "subsystem": "applications", 110 "parts": { 111 "prebuilt_hap": { 112 "module_list": [ 113 ... 114 "//applications/standard/example:example" # 添加编译目标 115 ] 116 } 117 } 118 } 119 ``` 120 1214. 编译命令： 122 ``` 123 # 全量编译 124 ./build.sh --product-name {product_name} 125 126 # 单独编译HAP 127 ./build.sh --product-name {product_name} --build-target applications/standard/example:example 128 ``` 129 1305. 编译产物，FA模型简单例子HAP解压视图如下： 131 ``` 132 Length Date Time Name 133 --------- ---------- ----- ---- 134 1439 2009-01-01 00:00 assets/raw_assets -----> raw_assets 135 354 2009-01-01 00:00 assets/entry/resources.index ------> resources 136 1 2009-01-01 00:00 assets/entry/resources/base/media/attributes.key ------> resources 137 1 2009-01-01 00:00 assets/entry/resources/base/media/constants.key ------> resources 138 1 2009-01-01 00:00 assets/entry/resources/base/media/contents.key ------> resources 139 6790 2009-01-01 00:00 assets/entry/resources/base/media/icon.png ------> resources 140 1 2009-01-01 00:00 assets/entry/resources/base/media/nodes.key ------> resources 141 11170 2009-01-01 00:00 assets/js/default/app.js ------> js_assets 142 48 2009-01-01 00:00 assets/js/default/i18n/en-US.json ------> js_assets 143 50 2009-01-01 00:00 assets/js/default/i18n/zh-CN.json ------> js_assets 144 224 2009-01-01 00:00 assets/js/default/manifest.json ------> js_assets 145 41481 2009-01-01 00:00 assets/js/default/pages/index/index.js ------> js_assets 146 909 2009-01-01 00:00 config.json ------> hap_profile 147 266248 2009-01-01 00:00 libs/libpng.z.so ------> shared_libraries 148 ``` 149 150### gn脚本配置示例 151- FA模型多ability示例 152 153 ``` 154 import("//build/ohos.gni") 155 156 ohos_hap("dataability") { 157 hap_profile = "entry/src/main/config.json" 158 deps = [ 159 ":dataability_js_assets", 160 ":dataability_resources", 161 ] 162 certificate_profile = "signature/openharmony_sx.p7b" 163 hap_name = "dataability" 164 part_name = "prebuilt_hap" 165 subsystem_name = "applications" 166 } 167 168 ohos_js_assets("dataability_js_assets") { 169 ets2abc = true 170 source_dir = "entry/src/main/ets" 171 hap_profile = "entry/src/main/config.json" 172 } 173 174 ohos_resources("dataability_resources") { 175 sources = [ 176 "entry/src/main/resources", 177 ] 178 hap_profile = "entry/src/main/config.json" 179 } 180 181 ``` 182 183- FA模型Js卡片示例 184 185 ``` 186 import("//build/ohos.gni") 187 188 ohos_hap("FormOfFaJs") { 189 hap_profile = "entry/src/main/config.json" 190 deps = [ 191 ":FormOfFaJs_js_assets", 192 ":FormOfFaJs_resources", 193 ] 194 certificate_profile = "signature/openharmony_sx.p7b" 195 hap_name = "FormOfFaJs" 196 part_name = "prebuilt_hap" 197 subsystem_name = "applications" 198 } 199 200 ohos_js_assets("FormOfFaJs_js_assets") { 201 hap_profile = "entry/src/main/config.json" 202 js2abc = true 203 source_dir = "entry/src/main/js" 204 } 205 206 ohos_resources("FormOfFaJs_resources") { 207 sources = [ 208 "entry/src/main/resources", 209 ] 210 hap_profile = "entry/src/main/config.json" 211 } 212 ``` 213 214- FA模型Ets卡片示例 215 216 ``` 217 import("//build/ohos.gni") 218 219 ohos_hap("FormOfFaEts") { 220 hap_profile = "entry/src/main/config.json" 221 deps = [ 222 ":FormOfFaEts_js_assets", 223 ":FormOfFaEts_form_js_assets", 224 ":FormOfFaEts_resources", 225 ] 226 certificate_profile = "signature/openharmony_sx.p7b" 227 hap_name = "FormOfFaEts" 228 part_name = "prebuilt_hap" 229 subsystem_name = "applications" 230 } 231 232 ohos_js_assets("FormOfFaEts_js_assets") { 233 hap_profile = "entry/src/main/config.json" 234 ets2abc = true 235 source_dir = "entry/src/main/ets" 236 } 237 238 ohos_js_assets("FormOfFaEts_form_js_assets") { 239 hap_profile = "entry/src/main/config.json" 240 js2abc = true 241 source_dir = "entry/src/main/js" 242 } 243 244 ohos_resources("FormOfFaEts_resources") { 245 sources = [ 246 "entry/src/main/resources", 247 ] 248 hap_profile = "entry/src/main/config.json" 249 } 250 ``` 251 252- Stage模型简单示例 253 254 ``` 255 import("//build/ohos.gni") 256 257 ohos_hap("actmoduletest") { 258 hap_profile = "entry/src/main/module.json" 259 deps = [ 260 ":actmoduletest_js_assets", 261 ":actmoduletest_resources", 262 ] 263 certificate_profile = "signature/openharmony_sx.p7b" 264 hap_name = "actmoduletest" 265 part_name = "prebuilt_hap" 266 subsystem_name = "applications" 267 } 268 269 ohos_app_scope("actmoduletest_app_profile") { 270 app_profile = "AppScope/app.json" 271 sources = [ "AppScope/resources" ] 272 } 273 274 ohos_js_assets("actmoduletest_js_assets") { 275 ets2abc = true 276 source_dir = "entry/src/main/ets" 277 } 278 279 ohos_resources("actmoduletest_resources") { 280 sources = [ 281 "entry/src/main/resources", 282 ] 283 deps = [ 284 ":actmoduletest_app_profile", 285 ] 286 hap_profile = "entry/src/main/module.json" 287 } 288 ``` 289 290- Stage模型卡片示例 291 292 ``` 293 import("//build/ohos.gni") 294 295 ohos_hap("FormOfStageEts") { 296 hap_profile = "entry/src/main/module.json" 297 deps = [ 298 ":FormOfStageEts_js_assets", 299 ":FormOfStageEts_form_js_assets", 300 ":FormOfStageEts_resources", 301 ] 302 js_build_mode = "debug" # 默认release 303 certificate_profile = "signature/openharmony_sx.p7b" 304 hap_name = "FormOfStageEts" 305 part_name = "prebuilt_hap" 306 subsystem_name = "applications" 307 } 308 309 ohos_js_assets("FormOfStageEts_js_assets") { 310 hap_profile = "entry/src/main/module.json" 311 ets2abc = true 312 source_dir = "entry/src/main/ets" 313 } 314 315 ohos_js_assets("FormOfStageEts_form_js_assets") { 316 hap_profile = "entry/src/main/module.json" 317 js2abc = true 318 source_dir = "entry/src/main/js" 319 } 320 321 ohos_app_scope("FormOfStageEts_app_profile") { 322 app_profile = "AppScope/app.json" 323 sources = [ "AppScope/resources" ] 324 } 325 326 ohos_resources("FormOfStageEts_resources") { 327 sources = [ 328 "entry/src/main/resources", 329 ] 330 deps = [ 331 ":FormOfStageEts_app_profile", 332 ] 333 hap_profile = "entry/src/main/module.json" 334 } 335 ``` 336
