• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# HAP
2
3The Harmony Ability Package (HAP) is the basic unit for installing and running applications. A HAP is a module package consisting of code, resource files, third-party libraries, and an application configuration file. There are two types of HAPs: entry and feature.
4
5- entry: main module of and entry to an application, providing the basic application functionality.
6- feature: dynamic feature module of an application, extending the application functionality. This type of HAP can be installed based on user needs and device types.
7
8An application package can contain either only one entry HAP or one entry HAP plus one or more feature HAPs.
9
10## When to Use
11
12- Single HAP: If your application only uses the UIAbility (that is, no ExtensionAbility is required), a single HAP (entry HAP) is recommended. While a HAP can contain one or more UIAbilities, adopt the "one UIAbility + multiple pages" mode to avoid unnecessary resource loading.
13
14- Multi-HAP: If your application needs to use ExtensionAbilities, develop multiple HAPs (one entry HAP and one or more feature HAPs) for it, with each HAP containing one UIAbility or one ExtensionAbility. Note that repeated packaging may arise if these HAPs reference the same library file.
15
16
17## Constraints
18
19- APIs and ArkUI components cannot be exported from the HAP to other modules.
20
21- In an App Pack that contains multiple HAPs, each type of device supports only one entry HAP and zero, one, or more feature HAPs.
22
23- If an application has multiple HAPs, the settings of the following parameters must be consistent across the configuration files of these HAPs: **bundleName**, **versionCode**, **versionName**, **minCompatibleVersionCode**, **debug**, **minAPIVersion**, **targetAPIVersion**, and **apiReleaseType**. The value of **moduleName** for any HAP of the same device type must be unique. The IDE validates the settings of these parameters when packaging the HAPs into an App Pack.
24
25- If an application has multiple HAPs, the signing certificates of all HAPs and HSPs of this application must be the same. Applications are released to the application market in the form of App Pack after being signed. Before distribution, the application market splits an App Pack into HAPs and resigns them to ensure the consistency of HAP signing certificates. Before installing HAPs on a device through the CLI or DevEco Studio for debugging purposes, ensure that their signing certificates are the same. Otherwise, the installation will fail.
26
27## Creating a HAP
28
29To create a HAP in DevEco Studio:
30
311. Create a project. For details, see [Building the First ArkTS Application in Stage Model](start-with-ets-stage.md).
322. Right-click the project directory and choose **New** > **Module** from the shortcut menu.
333. In the dialog box displayed, select **Empty Ability** as the template and click **Next**.
34
354. On the module configuration page, set **Module name**, **Module Type**, and **Device Type**, and click **Next**.
36
375. On the ability configuration page, set **Ability name** and click **Finish**.
38
39## Developing a HAP
40
41- You can add a UIAbility or ExtensionAbility to a HAP.
42
43- You can also configure a HAP to reference a HAR or HSP. For details, see [Using a HAR](./har-package.md#using-a-har) and [Using an HSP](./in-app-hsp.md#using-an-hsp).
44
45## Debugging a HAP
46
47After building code into one or more HAPs and installing or updating these HAPs, you can debug them. You can leverage a single set of code and files to build multiple target editions for different audiences, deployment environments, operating environments, and more.
48
49To debug a HAP, use either of the following tools:
50
51- DevEco Studio
52
53- [hdc](../../device-dev/subsystems/subsys-toolchain-hdc-guide.md), which can be obtained from the **toolchains** folder in the OpenHarmony SDK
54
55   Before debugging a HAP, install or update it using either of the methods:
56
57   - Use hdc to install and update the HAP.
58
59      When specifying the HAP, use the path to it on the operating system. In the following example, the operating system is Windows:
60
61      ```shell
62      // Installation and update: Multiple file paths can be specified.
63      hdc install entry.hap feature.hap
64      // Execution result
65      install bundle successfully.
66      // Uninstall
67      hdc uninstall com.example.myapplication
68      // Execution result
69      uninstall bundle successfully.
70      ```
71
72   - Run the hdc shell command, and then use the Bundle Manager (bm) tool to install and update the HAP.
73
74      When specifying the HAP, use the path to it on the real device. The sample code is as follows:
75
76      ```shell
77      // Run the hdc shell command before using the bm tool.
78      hdc shell
79      // Installation and update: Multiple file paths can be specified.
80      bm install -p /data/app/entry.hap /data/app/feature.hap
81      // Execution result
82      install bundle successfully.
83      // Uninstall
84      bm uninstall -n com.example.myapplication
85      // Execution result
86      uninstall bundle successfully.
87      ```
88
89   After the HAP is installed or updated, you can debug it by following the instructions in [Ability Assistant](../tools/aa-tool.md).
90