To develop an application based on the [stage model](application-configuration-file-overview-stage.md), it is essential to understand the structure of the application package created after the application is built and packaged.
To develop an application based on the [stage model](application-configuration-file-overview-stage.md), it will be helpful if you have a basic understanding of the structure of the application package created after the application is built and packaged, as well as the related basic concepts.
- In development, an application contains one or more modules. You can [create modules](https://developer.harmonyos.com/en/docs/documentation/doc-guides-V3/ohos-adding-deleting-module-0000001218760594-V3) in the application project in [DevEco Studio](https://developer.harmonyos.com/en/develop/deveco-studio/). As a basic functional unit of an OpenHarmony application/service, a module contains source code, resource files, third-party libraries, and application/service configuration files, and can be built and run independently. Modules can be classified as Ability or Library. A module of the Ability type is built into a Harmony Ability Package (HAP) file in .hap format, and a module of the Library type is built into a [Harmony Ability Resources (HAR) file](har-structure.md) in .tgz format.
- In development, an application contains one or more modules. You can [create modules](https://developer.harmonyos.com/en/docs/documentation/doc-guides-V3/ohos-adding-deleting-module-0000001218760594-V3) in the application project in [DevEco Studio](https://developer.harmonyos.com/en/develop/deveco-studio/). As a basic functional unit of an OpenHarmony application/service, a module contains source code, resource files, third-party libraries, and application/service configuration files, and can be built and run independently. Modules can be classified as Ability or Library. A module of the Ability type is built into a Harmony Ability Package (HAP) file, and a module of the Library type is built into a [Harmony Archive (HAR)](har-package.md) file or a [Harmony Shared Package (HSP)](shared-guide.md).
A module can contain one or more [UIAbility](../application-models/uiability-overview.md) components, as shown in the figure below.
**Figure 1** Relationship between modules and UIAbility components
**Figure 1** Relationship between modules and UIAbility components
Unless otherwise specified, the modules described in this document refer to the modules of the Ability type.
Unless otherwise specified, the modules described in this document refer to the modules of the Ability type.
- As aforementioned, you can build an application into one or more HAP files. The HAP file is the basic unit for installing an application. It provides code, resources, third-party libraries, and a configuration file. HAP files can be classified as Entry or Feature.
- HAP of the entry type: main module of the application, whose **type** field is set to **"entry"** in the [module.json5](module-configuration-file.md) file. In an application, each type of device supports only one HAP of the entry type, which is typically used to implement the application's entry screen, entry icon, or headline feature.
...
...
@@ -27,6 +27,6 @@ To develop an application based on the [stage model](application-configuration-f
- The **module.json** file is the configuration file indispensable in a HAP file. It consists of **module.json5** and **app.json5** in the project configuration. While DevEco Studio provides default configuration, you must modify the configuration as needed. For details about the configuration fields, see [Application Configuration Files in Stage Model](application-configuration-file-overview-stage.md).
- The **pack.info** file describes the HAP attributes in the bundle, for example, **bundleName** and **versionCode** in **app** and **name**, **type**, and **abilities** in **module**. The file is automatically generated when DevEco Studio generates the bundle.
**Figure 2** Application package structure in stage model
\ No newline at end of file
**Figure 2** Application package structure in stage model
An inter-application Harmony Shared Package (HSP) is a file used for code and resource sharing between the host application and other applications.
The host application of an inter-application HSP is a special form of application, which consists of only one HSP. Instead of running independently on a device, the host application runs by being referenced by dependencies of common application modules. When a common application is running, it can invoke capabilities provided by the inter-application HSP dynamically as needed.
## Precautions
1. The code of an inter-application HSP runs in the application process. When invoking the code, implement an exception capture and fault tolerance mechanism to avoid stability issues caused by malfunctioning of the inter-application HSP.
2. An application can depend on multiple inter-application HSP files at the same time.
3. The inter-application HSP may slow down the startup of the application that depends on it. To avoid significant increase in the startup delay, limit the number of inter-application HSP dependencies within 16.
4. Third-party developers can only use the system-provided inter-application HSP files.
## Inter-Application HSP Usage
An inter-application HSP works by combining the following parts:
[HAR](har-package.md): contains only objects and methods to be exported and therefore comes in a small size. By integrating the HAR into your application project, you can call the objects and methods therein to implement features.
HSP: contains the actual implementation code, including the JS/TS code, C++ libraries, resources, and configuration files. It is either released to the application market or integrated into the system version.
### Integrating the HAR in an Inter-Application HSP
Define the interfaces to be exported in the **index.d.ets** file in the HAR, which is the entry to the declaration file exported by the inter-application HSP. The path of the **index.d.ets** file is as follows:
```
src
├── main
| └── module.json5
├── index.d.ets
└── package.json
```
Below is an example of the **index.d.ets** file content:
```ts
@Component
exportdeclarestructUIComponent{
build():void;
}
exportdeclarefunctionhello():string;
exportdeclarefunctionfoo1():string;
exportdeclarefunctionfoo2():string;
exportdeclarefunctionnativeHello():string;
```
In the example, **UIComponent** is an ArkUI component, **hello()**, **foo1()**, and **foo2()** are TS methods, and **nativeHello()** is an native method. Specific implementation is as follows:
#### ArkUI Components
The following is an implementation example of ArkUI components in the HSP:
```ts
// lib/src/main/ets/ui/MyUIComponent.ets
@Component
exportstructUIComponent{
@Statemessage:string='Hello World'
build(){
Column(){
Text(this.message)
.fontSize(32)
.padding(8)
.fontColor(0xffffff)
.backgroundColor(0x0000ff)
}.padding(8).width('100%')
}
}
```
#### **TS Methods**
The following is an implementation example of TS methods in the HSP:
```ts
exportfunctionhello(name:string):string{
return"hello + "+name;
}
exportfunctionfoo1(){
return"foo1";
}
exportfunctionfoo2(){
return"foo2";
}
```
#### **Native Methods**
The following is an implementation example of native methods in the HSP:
To start with, [configure dependency](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ohos-development-npm-package-0000001222578434#section89674298391) on the HAR. The dependency information will then be generated in the **module.json** file of the corresponding module, as shown in the following:
```json
"dependencies":[
{
"bundleName":"com.share.liba",
"moduleName":"liba",
"versionCode":10001
}
]
```
In the preceding information, **bundleName**, **moduleName**, and **versionCode** indicate the bundle name, module name, and version number of the inter-application HSP, respectively.
#### Referencing ArkUI Components in the HAR
After configuring the dependency on the HAR, you can reference ArkUI components exported from the HAR by using **import**. The sample code is as follows:
``` ts
import{UIComponent}from'liba'
@Entry
@Component
structIndex{
@Statemessage:string='Hello World'
build(){
Row(){
// Reference the ArkUI component in the HAR.
UIComponent()
Column(){
Text(this.message)
.fontSize(50)
.fontWeight(FontWeight.Bold)
}
.width('100%')
}
.height('100%')
}
}
```
#### Referencing TS Classes and Methods in the HAR
To reference the TS classes and methods exported from the HAR, use **import** as follows:
``` ts
import{foo1}from'liba'
import{foo2}from'liba'
@Component
structIndex{
build(){
Row(){
Column(){
Button('Button')
.onClick(()=>{
// Reference the TS methods in the HAR.
foo1();
foo2();
})
}
.width('100%')
}
.height('100%')
}
}
```
#### Referencing Native Methods in the HAR
To reference the native methods exported from the HAR, use **import** as follows:
``` ts
import{nativeHello}from'liba'
@Component
structIndex{
build(){
Row(){
Column(){
Button('Button')
.onClick(()=>{
// Reference the native method in the HAR.
nativeHello();
})
}
.width('100%')
}
.height('100%')
}
}
```
## Inter-Application HSP Distribution
Inter-application HSPs are not completely integrated into an application. They are distributed by being preset in the system version or installed with an application on the device. To be specific:
1. Some frequently-used inter-application HSPs are preset in the system version.
2. When a user downloads an application from the application market, if the application market detects that the application depends on one or more inter-application HSPs and any of these HSPs are not installed on the target device, it will download the application as well as the missing HSPs for the user. In this way, the application can use the features shared through the HSPs properly.
### Inter-Application HSP Debugging Mode
You can debug an inter-application HSP after it is distributed to a device. If the aforementioned distribution methods are not applicable, you can distribute the HSP by running **bm** commands. The procedure is as follows:
> **NOTE**
>
> Do not reverse steps 2 and 3. Otherwise, your application will fail to be installed due to a lack of the required inter-application HSP. For more information about the **bm** commands, see [Bundle Management](../../readme/bundle-management.md).
1. Obtain the inter-application HSP installation package.
2. Run the following **bm** command to install the inter-application HSP.
```
bm install -s sharebundle.hsp
```
3. Run the following **bm** command to install the HAP file of your application.
A Harmony Archive (HAR) is a static shared package that can contain code, C++ libraries, resources, and configuration files. It enables modules and projects to share code related to ArkUI components, resources, and more. Unlike a Harmony Ability Package (HAP), a HAR cannot be independently installed on a device. Instead, it can be referenced only as the dependency of an application module.
## Creating a HAR Module
You can kickstart your HAR module development with the module template of the **Library** type in DevEco Studio. By default, obfuscation is disabled for the HAR module. To enable this feature, set **artifactType** in the **build-profile.json5** file of the HAR module to **obfuscation** as follows:
```json
{
"apiType":"stageMode",
"buildOption":{
"artifactType":"obfuscation"
}
}
```
The value options of **artifactType** are as follows, and the default value is **original**:
-**original**: Code is not obfuscated.
-**obfuscation**: Code is obfuscated using Uglify.
When obfuscation is enabled, DevEco Studio compiles, obfuscates, and compresses code during HAR building, thereby protecting your code assets.
> **NOTE**
>
> If **artifactType** is set to **obfuscation**, **apiType** must be set to **stageMode**, because obfuscation is available only in the stage model.
## Precautions for HAR Development
- The HAR does not support the declaration of **abilities** and **extensionAbilities** in its configuration file.
- The HAR does not support the declaration of pages in its configuration file.
- The HAR does not support **worker** configuration under **buildOption** in the **build-profile.json5** file.
- The HAR of the FA model and that of the stage model cannot be referenced by each other.
- The HAR of the stage model cannot reference content in the **AppScope** folder. This is because the content in the **AppScope** folder is not packaged into the HAR during compilation and building.
## Exporting ArkUI Components, APIs, and Resources of the HAR
The **index.ets** file acts as the entry of the HAR export declaration file and is where the HAR exports APIs. This file is automatically generated by DevEco Studio by default. You can specify another file as the entry declaration file in the **main** field in the **package.json** file of the module. The code snippet is as follows:
```json
{
"main":"index.ets"
}
```
### Exporting ArkUI Components
Use **export** to export the ArkUI components. The code snippet is as follows:
Use **export** to export TS classes and methods. Multiple TS classes and methods can be exported at the same time. The code snippet is as follows:
```js
// library/src/main/ts/test.ets
exportclassLog{
staticinfo(msg){
console.info(msg);
}
}
exportfunctionfunc(){
return"har func";
}
exportfunctionfunc2(){
return"har func2";
}
```
In the **index.ets** file, declare the APIs that the HAR exposes to external systems. The code snippet is as follows:
```js
// library/index.ets
export{Log}from'./src/main/ts/test'
export{func}from'./src/main/ts/test'
export{func2}from'./src/main/ts/test'
```
### Resources
Resources are packed into the HAR when it is being compiled and packaged. During compilation and building of a HAP, DevEco Studio collects resource files from the HAP module and its dependent modules. If the resource files of different modules have the same name, DevEco Studio overwrites the resource files based on the following priorities (in descending order):
- AppScope (supported only by the stage model of API version 9)
- Modules in the HAP file
- If resource conflicts occur between dependent HAR modules, they are overwritten based on the dependency sequence. (The module that is higher in the dependency sequence list has higher priority.)
## Referencing ArkUI Components, APIs, and Resources in the HAR
To start with, [configure dependency](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ohos-development-npm-package-0000001222578434#section89674298391) on the HAR.
### Reference ArkUI Components in the HAR
After configuring the dependency on the HAR, you can reference ArkUI components exported from the HAR by using **import**. The sample code is as follows:
```js
// entry/src/main/ets/pages/index.ets
import{MainPage}from"@ohos/library"
@Entry
@Component
structIndex{
@Statemessage:string='Hello World'
build(){
Row(){
// Reference the ArkUI component in the HAR.
MainPage()
Column(){
Text(this.message)
.fontSize(50)
.fontWeight(FontWeight.Bold)
}
.width('100%')
}
.height('100%')
}
}
```
### Referencing TS Classes and Methods in the HAR
To reference the TS classes and methods exported from the HAR, use **import** as follows:
```js
// entry/src/main/ets/pages/index.ets
import{Log}from"@ohos/library"
import{func}from"@ohos/library"
@Entry
@Component
structIndex{
build(){
Row(){
Column(){
Button('Button')
.onClick(()=>{
// Reference TS classes and methods in the HAR.
Log.info("har msg");
func();
})
}
.width('100%')
}
.height('100%')
}
}
```
### Referencing Resources in the HAR
Use **$r** to reference resources in the HAR. For example, add the **name: hello_har** string (defined in the **string.json** file) and **icon_har.png** image to the **src/main/resources** directory of the HAR module, and then reference the string and image in the entry module. The code snippet is as follows:
An in-application Harmony Shared Package (HSP) is a file used for code and resource sharing within an application (called the host application) and can only be invoked by a HAP or HSP of the same application.
The in-application HSP is released with the Application Package (App Pack) of the host application and has the same bundle name and lifecycle as the host application.
## Developing an In-Application HSP
You can kickstart your HSP development with the HSP template in DevEco Studio. In this example, an HSP module named **library** is created. The basic project directory structure is as follows:
```
library
├── src
│ └── main
│ ├── ets
│ │ ├── pages
│ │ └── index.ets
│ ├── resources
│ └── module.json5
└── package.json
```
In the **module.json5** file, set **type** to **shared** for the HSP.
```json
{
"type":"shared"
}
```
The HSP provides capabilities for external systems by exporting APIs in the entry file. Specify the entry file in **main** in the **package.json** file. For example:
```json
{
"main":"./src/main/ets/index.ets"
}
```
### Exporting TS Classes and Methods
Use **export** to export TS classes and methods. The sample code is as follows:
```ts
// library/src/main/ets/utils/test.ts
exportclassLog{
staticinfo(msg){
console.info(msg);
}
}
exportfunctionadd(a:number,b:number){
returna+b;
}
exportfunctionminus(a:number,b:number){
returna-b;
}
```
In the entry file **index.ets**, declare the APIs to be exposed.
```ts
// library/src/main/ets/index.ets
export{Log,add,minus}from'./utils/test'
```
### Exporting ArkUI Components
Use **export** to export ArkUI components. The sample code is as follows:
```ts
// library/src/main/ets/components/MyTitleBar.ets
@Component
exportstructMyTitleBar{
build(){
Row(){
Text($r('app.string.library_title'))
.fontColor($r('app.color.white'))
.fontSize(25)
.margin({left:15})
}
.width('100%')
.height(50)
.padding({left:15})
.backgroundColor('#0D9FFB')
}
}
```
In the entry file **index.ets**, declare the APIs to be exposed.
```ts
// library/src/main/ets/index.ets
export{MyTitleBar}from'./components/MyTitleBar'
```
#### About Using Resources in the HSP
To reference resources in the **resources** directory of the current HSP module, use **$r** or **$rawfile**.
If a relative path is used, the resources in the HSP caller are referenced instead. For example,
if **Image("common/example.png")** is used in the HSP module, the **\<Image>** component will reference the resource **entry/src/main/ets/common/example.png** in the HSP caller (which is **entry** in this example).
### Exporting Native Methods
The HSP can contain .so files compiled in C++. The HSP indirectly exports the native method in the .so file. In this example, the **multi** method in the **libnative.so** file is exported.
```ts
// ibrary/src/main/ets/utils/nativeTest.ts
importnativefrom"libnative.so"
exportfunctionnativeMulti(a:number,b:number){
returnnative.multi(a,b);
}
```
In the entry file **index.ets**, declare the APIs to be exposed.
```ts
// library/src/main/ets/index.ets
export{nativeMulti}from'./utils/nativeTest'
```
## Using the In-Application HSP
To use APIs in the HSP, first configure the dependency on the HSP in the **package.json** file of the module that needs to call the APIs (called the invoking module). If the HSP and the invoking module are in the same project, the APIs can be referenced locally. The sample code is as follows:
```json
//entry/src/main/module.json5
"dependencies":{
"library":"file:../library"
}
```
You can now call the external APIs of the HSP in the same way as calling the APIs in the HAR.
In this example, the external APIs are the following ones exported from **library**:
```ts
// library/src/main/ets/index.ets
export{Log,add,minus}from'./utils/test'
export{MyTitleBar}from'./components/MyTitleBar'
export{nativeMulti}from'./utils/nativeTest'
```
The APIs can be used as follows in the code of the invoking module:
OpenHarmony provides two types of shared packages: [Harmony Achive (HAR)](har-package.md) static shared package and Harmony Shared Package (HSP) dynamic shared package.
Both the HAR and HSP are used to share code and resources and can contain code, C++ libraries, resources, and configuration files. The biggest differences between them are as follows: The code and resources in the HAR are compiled with the invoking module, and if there are multiple invoking modules, the build product contains multiple copies of the same code and resources; the code and resources in the HSP can be compiled independently, and the build product contains only one copy of the code and resources.
**Figure 1** HAR and HSP in the App Pack
The HSP is designed to solve the following issues with the HAR:
- When multiple HAPs reference the same HAR, the size of the App Pack swells.
- When multiple HAPs reference the same HAR, some state variables in the HAR cannot be shared.
Restrictions on the HSP:
- The HSP and its invoking modules must be in the stage model.
- The HSP and its invoking modules must use the **esmodule **compilation mode.
- The HSP does not support the declaration of **abilities** and **extensionAbilities** in its configuration file.
The HSP can be classified as [in-application HSP](in-app-hsp.md) or [inter-application HSP](cross-app-hsp.md), depending on the configuration files and usage methods.
