HAP

Note:

Currently in the beta phase.

HAP (Harmony Ability Package) is the fundamental unit for application installation and operation. A HAP package is a modular bundle generated by packaging code, resources, third-party libraries, configuration files, etc. It primarily falls into two types: entry and feature.

• entry: The main module of an application, serving as the entry point that provides the application's core functionality.
• feature: The dynamic feature module of an application, acting as an extension of application capabilities that can be selectively installed based on user requirements and device types.

An application package may consist solely of a basic entry package or include one basic entry package along with multiple functional feature packages.

Usage Scenarios

• Single HAP Scenario: If only UIAbility components are required without ExtensionAbility components, prioritize using a single HAP (i.e., one entry package) for application development. Although a single HAP may contain one or more UIAbility components, to avoid unnecessary resource loading, it is recommended to adopt the "one UIAbility + multiple pages" approach.

• Multi-HAP Scenario: For applications with complex functionalities requiring ExtensionAbility components, employ multiple HAPs (i.e., one entry package + multiple feature packages) for development. Each HAP should contain either one UIAbility component or one ExtensionAbility component. In this scenario, multiple HAPs referencing the same library files may lead to duplicate packaging issues.

Constraints

• Exporting interfaces and Cangjie components for use by other modules is not supported.

• In multi-HAP scenarios, an App Pack package can contain at most one Entry-type HAP per device type, or none at all. Feature-type HAPs may include one or multiple instances, or none.

• In multi-HAP scenarios, all HAPs within the same application must have identical configurations for bundleName, versionCode, versionName, minCompatibleVersionCode, debug, minAPIVersion, targetAPIVersion, and apiReleaseType in their configuration files. Additionally, the moduleName tag must be unique across all HAPs for the same device type. When packaging HAPs into an App Pack, these parameters are validated.

• In multi-HAP scenarios, all HAPs of the same application must maintain consistent signing certificates. When publishing to app stores in the form of an App Pack, the store will split out all HAPs from the App Pack and re-sign them to ensure certificate consistency. During debugging, developers must ensure all HAPs installed via command line or DevEco Studio share the same signing certificate; otherwise, installation may fail. For signing operations, refer to Application/Meta Service Signing.

Creation

Below is a brief guide on creating a new HAP module via DevEco Studio.

1. Create a project to build your first Cangjie application.

2. Right-click on the project directory and select New > Module.

3. In the dialog that appears, choose the "[Cangjie] Empty Ability" template and click Next.

4. On the Module configuration screen, configure the Module name, select Module Type and Device Type, then click Next.

5. On the Ability configuration screen, specify the Ability name and click Finish to complete creation.

Development

• Cangjie HAPs support referencing HARs. For details, see HAR Usage.

Debugging

Compile and package via DevEco Studio to generate single or multiple HAPs for debugging. To customize compile the same HAP into different versions based on deployment environments, target audiences, or runtime conditions, refer to Customized Compilation Guide.

Developers can debug using DevEco Studio or the hdc tool:

• Method 1: Debug with DevEco Studio. For details, see Application Package Debugging Methods .

• Method 2: Debug using the hdc tool.

  Before debugging, install or update the HAP via either of the following methods:

  • Directly install/update HAP using hdc.

    The HAP path refers to the file path on the development platform. For Windows, commands are as follows:

    # Install/update; multiple HAPs can be specified with multiple file paths
    hdc install entry.hap feature.hap
    # Execution result
    install bundle successfully.
    # Uninstall
    hdc uninstall com.example.myapplication
    # Execution result
    uninstall bundle successfully.
    

  • Execute hdc shell first, then use the bm tool to install/update HAP.

    The HAP file path refers to the path on the physical device. Commands are as follows:

    # Execute hdc shell to enable bm tool usage
    hdc shell
    # Install/update; multiple HAPs can be specified with multiple file paths
    bm install -p /data/app/entry.hap /data/app/feature.hap
    # Execution result
    install bundle successfully.
    # Uninstall
    bm uninstall -n com.example.myapplication
    # Execution result
    uninstall bundle successfully.
    

  After HAP installation or update, proceed with debugging using relevant debugging commands.