Skip to content

D
Docs

OpenHarmony / Docs
大约 1 年 前同步成功

通知 159
Star 292
Fork 28
D
Docs
提交 2b8d818c 编写于 作者: W wusongqing
浏览文件
操作

Added English HPM Part 

Signed-off-by: Nwusongqing <wusongqing@huawei.com>
上级 f0336962
隐藏空白更改
内联 并排
Showing with 833 addition and 1245 deletion
en/device-dev/bundles/Readme-EN.md
浏览文件 @ 2b8d818c
# Bundle Development
# Bundles
- [Development Specifications](bundles-standard-rules.md)
- [Development Guidelines](bundles-guide.md)
- [Bundle Development](bundles-guide-overview.md)
- [Preparations](bundles-guide-prepare.md)
- [Bundle Development](bundles-guide-develop.md)
- [HPM User Guide](bundles-demo.md)
- [Introduction](bundles-demo-hpmdescription.md)
- [Preparations](bundles-demo-environment.md)
- [Development Example](bundles-demo-devsample.md)
\ No newline at end of file
- [HPM Part Overview](hpm-part-about.md)
- [HPM Part Development](hpm-part-development.md)
- [HPM Part Reference](hpm-part-reference.md)
en/device-dev/bundles/bundles-demo-devsample.md 已删除 100644 → 0
浏览文件 @ f0336962
# Development Example<a name="EN-US_TOPIC_0000001072143838"></a>
The following uses the Hi3861 platform as an example to describe how to install and build bundles by using the hpm.
1. Run the following commands to create a directory \(its name can be customized\) and create a default project based on the dist template:
```
mkdir test3861
cd test3861
hpm init -t dist myproduct
```
If the following information is displayed, the project is created:
```
Initialization finished.
```
2. Run the following command to install the **hispark\_pegasus** distribution:
```
hpm install @ohos/hispark_pegasus
```
If the following information is displayed, the installation is successful:
```
Installed.
```
>![](../public_sys-resources/icon-note.gif) **NOTE:**
>If you are using the Hi3516 platform, run the following command:
>```
>hpm install @ohos/hispark_taurus
>```
>If you are using the Hi3518 platform, run the following command:
>```
>hpm install @ohos/hispark_aries
>```
3. Run the following command to build and package bundles:
```
hpm dist
```
If the building is successful, the following information is displayed:
```
{{name}}: distribution building completed.
```
4. Check the result in the **./out** directory. You can burn the distribution into the corresponding development board for testing.
en/device-dev/bundles/bundles-demo-environment.md 已删除 100644 → 0
浏览文件 @ f0336962
# Configuring the Compilation Environment<a name="EN-US_TOPIC_0000001071315859"></a>
![](figure/3516dv300.png)
## Linux Server<a name="section20979554791"></a>
Prepare a 64-bit Linux server running Ubuntu 16.04 or later. \(Currently, the compilation in the Windows environment is not fully supported.\)
Configure Ubuntu to use bash as the Linux system shell, by performing the following:
```
ls -l $(which sh)
# If the file does not point to bash, modify the file using either of the provided methods.
# Method 1: Run the following command and select no:
dpkg-reconfigure dash
# Method 2: Run the following commands to delete /bin/sh and then create a new symbolic link to bash:
rm -f /bin/sh
ln -s bash /bin/sh
```
## Node.js<a name="section9954105413153"></a>
>![](../public_sys-resources/icon-note.gif) **NOTE:**
>If the **Node.js** version of the source is outdated, run the following command before running **apt-get install**:
>```
>curl -L https://deb.nodesource.com/setup_12.x | bash
>```
You are advised to install Node.js 12.x \(including npm 6.14.4\) or a later version \(12.13.0 or later is recommended\).
```
sudo apt-get install nodejs
sudo apt-get install npm
```
Run the following commands to view **Node.js** and npm versions:
```
node --version # Check the Node.js version.
npm --version # Check the npm version.
```
## Installing hpm-cli Tool<a name="section15937194904819"></a>
Install the **hpm-cli** command line tool by using the npm \(default source: https://registry.npmjs.org/\) provided by **Node.js**.
```
npm install -g @ohos/hpm-cli
```
After **hpm-cli** is installed, run the following command to view the default hpm configurations:
```
hpm config
```
You can modify the default configurations as required. The following lists common hpm configurations:
```
registry = https://hpm.harmonyos.com # Address of the hpm registry. This is mandatory for downloading bundles.
strictSsl = true # Enable strict SSL verification as HTTPS is used for connection.
http_proxy = http://your-proxy-server:port # Configure the HTTP proxy.
https_proxy = http://your-proxy-server:port # Configure the HTTPS proxy.
```
For details about **hpm-cli** commands, see [HPM Commands](bundles-standard-rules.md).
## Python Environment<a name="section1621819180417"></a>
Run the following commands to install Python later than 3.7:
```
sudo apt-get install python3.8
sudo apt-get install python3-pip
sudo pip3 install setuptools
sudo pip3 install kconfiglib # Install kconfiglib 13.2.0 or later.
```
>![](../public_sys-resources/icon-note.gif) **NOTE:**
>The preceding method is applicable to Hi3518 and Hi3516 platforms. For Hi3861, run the following commands to install the Python environment:
>```
>sudo apt-get install python3.8
>sudo apt-get install python3-pip
>sudo pip3 install setuptools
>sudo pip3 install kconfiglib # Install kconfiglib 13.2.0 or later.
>sudo pip3 install pycryptodome
>sudo pip3 install six --upgrade --ignore-installed six
>sudo pip3 install ecdsa
>```
If both Python2 and Python3 have been installed in the current system, run the following commands to set the default Python to Python3:
```
ll `which python`
rm /usr/bin/python
ln -s python3.8 /usr/bin/python
```
## File Packaging Tool<a name="section77617165913"></a>
Run the following commands to install the tool:
```
which mkfs.vfat # If mkfs.vfat is not found, run the following command:
sudo apt-get install dosfstools
which mcopy # If mcopy is not found, run the following command:
sudo apt-get install mtools
```
>![](../public_sys-resources/icon-note.gif) **NOTE:**
>Both Hi3518 and Hi3516 platforms require the file packaging tool. For Hi3861, the tool is not required.
## SCons<a name="section20558439191516"></a>
1. Start a Linux server.
2. Run the following command to install the SCons installation package:
```
python3 -m pip install scons
```
3. Run the following command to check whether SCons is successfully installed. If the installation is successful, the query result shown in [Figure 1](#fig235815252492) is displayed.
```
scons -v
```
**Figure 1** Successful installation \(SCons version requirement: 3.0.4 or later\)<a name="fig235815252492"></a>
![](figure/successful-installation-(scons-version-requirement-3-0-4-or-later)-28.png "successful-installation-(scons-version-requirement-3-0-4-or-later)-28")
>![](../public_sys-resources/icon-note.gif) **NOTE:**
>SCons is required for the Hi3861 platform, but not for the Hi3518 or Hi3516 platform.
en/device-dev/bundles/bundles-demo-hpmdescription.md 已删除 100644 → 0
浏览文件 @ f0336962
# Introduction<a name="EN-US_TOPIC_0000001071487274"></a>
HarmonyOS package manager \(hpm\) manages and distributes OpenHarmony bundles. It offers you a tool set to obtain and customize OpenHarmony source code and perform operations such as installation, building, packaging, and upgrade.
This document describes how to use the hpm to install, build, and package OpenHarmony bundles.
en/device-dev/bundles/bundles-demo.md 已删除 100644 → 0
浏览文件 @ f0336962
# HPM User Guide<a name="EN-US_TOPIC_0000001157479397"></a>
- **[Introduction](bundles-demo-hpmdescription.md)**
- **[Configuring the Compilation Environment](bundles-demo-environment.md)**
- **[Development Example](bundles-demo-devsample.md)**
en/device-dev/bundles/bundles-guide-develop.md 已删除 100644 → 0
浏览文件 @ f0336962
# Developing Bundles<a name="EN-US_TOPIC_0000001051690861"></a>
You can use any of the following methods to develop OpenHarmony bundles:
- Create a new bundle from scratch.
- Define an existing source code project as a bundle.
## Creating a Bundle<a name="section717481119145"></a>
Generally, you can find commonly used bundles on the [HPM](https://hpm.harmonyos.com/#/en/home) website. If they cannot meet your requirements, you can develop a bundle on your own.
You can publish bundles in the HPM repository if you like, so that your peers have an option to use them.
Assume that you are planning to create a new bundle **my-bundle** in **D:/source**. Run the **hpm init** command to create the scaffold code for this bundle. For example, you can go to **D:/source** and run the following command:
```
hpm init -t default -d demo mybundle
```
The **'default'** template will be used to create a bundle named **mybundle** in the **demo** directory in **D:/source**.
```
demo
├── headers # Header file (example)
│ └── main.h
└── src # Source code (example)
│ └─ main.c
├── bundle.json # Metadata declaration file
└── LICENSE # License agreement
└── Makefile # Compilation description file (example)
└── README.md # Readme file
```
Then, complete your coding based on service requirements and generate the build script. Finally, use **git** to commit your code \(including the **bundle.json** file\) to the code hosting repository, such as gitee.
>![](../public_sys-resources/icon-note.gif) **NOTE:**
>```
>hpm init -t {templatename} -d {dir} {name}
>```
>- **-t \{templatename\}** indicates the template name.
>- **-d \{dir\}** indicates the path for storing the bundle to be created.
>- **name** indicates the name of the bundle to be created.
The hpm provides a few default templates. More templates are available on the HPM server. You can run the **hpm search -t template** command to search for a template stored on the server.
![](figure/en-us_image_0000001134127844.png)
## Defining an Existing Project as a Bundle<a name="section102861955201410"></a>
If you have a code project and need to distribute it on the HPM platform, run the following command in the current project directory, for example, **mybundle2**:
```
hpm init
```
1. Enter a bundle name \(**mybundle2** as an example\) and press **Enter**.
2. Enter the version and description. A **bundle.json** file will be generated in the current directory.
3. Open the** bundle.json** file as you like.
```
$ hpm init
Your bundle will be created in directory ~\demo\mybundle2
? bundle name mybundel2
? version 1.0.0
...
Initialization finished.
```
1. Modify other information \(such as the author, code repository, code directory, command script, and dependent bundles\) in **bundle.json**. An example is shown below:
```
{
"name": "mybundle2",
"version": "1.0.0",
"publishAs": "code-segment",
"dirs":{
".":["README.md"],
"src":["test.c"],
"header":["header/test.h" ],
"src/common":["src/common/foobar.txt"]
},
"scripts": {
"build": "make -${args}"
},
"dependencies": {
"@ohos/cjson": "^1.0.0",
"@ohos/foobar": "^1.2.0"
}
}
```
## Releasing the Bundle on the HPM Platform<a name="section1318574233211"></a>
To release a bundle on the HPM platform, you need to obtain an account and create an organization \(or join an existing organization\). For details, see the online help on the [HPM](https://hpm.harmonyos.com/#/en/home) website.
After that, generate a public key on the local PC based on your invitation code \(which can be obtained on the **My profile** page on the HPM website\), and configure the public key on the **My profile** page.
```
hpm config set loginUser {your-invitation-code}
hpm gen-keys
```
The generated file will be stored in **\~\\Users\\yourname\\.hpm\\key**. Copy the content in the public key file **publicKey\_your-account.pem** to the SSH public key on your **My profile** page.
After finishing the preceding operations, you then have the permission to release bundles in your organization.
In the directory where the bundle is located, run the following command to package and release the bundle:
```
hpm publish
```
>![](../public_sys-resources/icon-note.gif) **NOTE:**
>- To avoid bundle name conflicts, name a released bundle in the format of **@org\_name/bundle\_name**.
>- Your account must also be a member of **org\_name** so that you can release or update bundles in the organization.
>- The released bundles take effect only after security and content reviews.
## Referencing a Bundle<a name="section19311124115315"></a>
Generally, when developing a project, you may need to reference other bundles in order to accelerate development of specific functions. Installing dependencies could be a good way.
Go to the HPM website, search for bundles that meet your service requirements by keywords, and then introduce the bundles to your project.
Run the following command in your bundle project. Make sure that the project directory contains the **bundle.json** file.
```
$ hpm install @scope/the_bundle
```
The referenced bundle will be installed under **ohos\_bundle** in the directory where your project is located. The directory structure is as follows:
```
project
├── ohos_bundle
│ └── scope
│ └─ the_bundle # <--- Referenced bundle
└── src
│ └─ main.c
├── bundle.json # Metadata declaration file
└── LICENSE
└── Makefile
└── README.md
```
Open the **bundle.json** file. You will see that the bundle has been introduced to the dependencies of your project.
```
{
"dependencies": {
"@scope/the_bundle": "^1.0.0"
}
}
```
You can also edit the dependencies of multiple bundles in this file at a time.
```
{
"dependencies": {
"@scope/the_bundle1": "^1.0.0",
"@scope/the_bundle2": "^2.0.0",
"@scope/the_bundle3": "^3.0.0",
"@scope/the_bundle4": "^1.1.0"
}
}
```
Run the **hpm install** command again to download and install all bundles that have not been installed.
## Installing a Bundle Globally<a name="section165131927192120"></a>
If the referenced bundle is one shared by multiple projects, for example, the compiler toolchain, you can install it globally.
Run the following command in your bundle project. Make sure that the project directory contains the **bundle.json** file.
```
$ hpm install -g @scope/the_tool
```
The referenced bundle will be installed in the directory specified by the **globalRepo** parameter of the **hpm config** command.
```
~\.hpm\global
│ └── scope
│ └─ the_tool # <--- Referenced bundle
```
>![](../public_sys-resources/icon-note.gif) **NOTE:**
>- For a bundle installed in a project, you can reference it using the environment variable **DEP\_SCOPE\_bundle\_name** when running the hpm compilation command.
>For example, after you run **hpm i @opensource/gn** to install a bundle, you can edit the build script in the **bundle.json** file as follows:
>```
>"scripts": {
> "build": "${DEP_OPENSOURCE_gn}/gn --version"
> },
>```
>Then, you can run the **hpm build** command to call GN functions.
>- For a globally installed bundle, you can directly call the bundle using an environment variable or reference the bundle using the **$\{key\}/tool\_name** parameter when running the **hpm config set key value** command. For example:
>```
>hpm i -g @ohos/opensource/gn
>hpm config BUILD_SYS_GN ~/.hpm/global/ohos_bundles/opensource/gn
>```
>You can edit the build script in the **bundle.json** file as follows:
>```
>"scripts": {
> "build": "${BUILD_SYS_GN}/gn --version"
> },
>```
>Then, you can run the **hpm build** command to call GN functions.
## Compiling a Bundle<a name="section136732148541"></a>
If the bundle code can be independently compiled once you finish coding, you can configure build tools and scripts to generate binary files.
The hpm supports command integration so that you can select any build tool \(such as **make**, **gcc**, and **gn**\) suitable for your project. You only need to define the **build** command in the **scripts** in the **bundle.json** file of your project, and then you run the hpm command **build** to perform building.
## Defining the Build Script<a name="section10274147111610"></a>
This section uses how to build an executable file **helloworld** in the **app** directory as an example.
```
app
├── BUILD.gn
├── include
│ └── helloworld.h
└── src
└── helloworld.c
```
Create a **BUILD.gn** file in the same directory as **helloworld.c**.
```
touch BUILD.gn
vim BUILD.gn
```
The following is an example of **BUILD.gn** for your reference:
```
executable("hello_world") {
sources = [
"src/helloworld.c"
]
include_dirs = [
"include"
]
}
```
>![](../public_sys-resources/icon-note.gif) **NOTE:**
>- **executable** is a built-in template of **gn**. You can run the **gn help executable** command to view how to use this template.
>- **sources** represents the source code path, and **include\_dirs** represents the header file path.
## Executing the Build Script<a name="section879301916172"></a>
Run the following command:
```
hpm build
```
After all building operations are complete, the message "build succeed" is displayed. You need to check the building result.
![](figure/en-us_image_0000001051770876.png)
## Defining a Distribution<a name="section413216495619"></a>
This process states the dependent bundles and how to compile and link the bundles to generate image files.
This section uses the hb compilation framework as an example.
## Defining Scripts<a name="section11503171219190"></a>
An example definition in the **bundle.json** file is as follows:
\{
"name": "@your/dist\_name",
"version": "2.2.0",
"publishAs": "distribution",
"description": "describe it",
"scripts": \{
"config\_hb": "hb set -root $DEP\_BUNDLE\_BASE",
"dist": "PATH=/root/.local/bin:$\{DEP\_OHOS\_gn\}:$\{DEP\_OHOS\_ninja\}/ninja:$\{DEP\_OHOS\_llvm\}/llvm/bin:$\{DEP\_OHOS\_hc\_gen\}/hc-gen:$\{PATH\} && ./scripts/dist.sh"
\},
"envs": \{
"debug": false
\},
"dirs": \{
"scripts": "scripts/\*"
\},
"dependencies": \{
"@ohos/build\_lite": "2.2.0",
"@ohos/gn": "1.1.1",
"@ohos/llvm": "1.1.1",
"@ohos/hc\_gen": "1.1.0",
"@ohos/ninja": "1.1.0",
...
\},
"ohos": \{
"os": "2.2-Beta",
"board": "hi3516",
"kernel": "liteos-a"
\},
"keywords": \[ "hispark", "hi3516" \],
"repository": "https://gitee.com/openharmony/your-project",
"license": "Apache V2"
\}
## Building a Distribution<a name="section4694125521912"></a>
Run the following command in the root directory of the current distribution:
```
hpm dist
```
The **hpm-cli** tool automatically starts compilation. After the compilation is complete, an image file will be generated, as shown below:
```
out
|-xxdist.img
|-xx.file
```
Burning
The build result of the distribution can be burnt into devices, for example, by using the **hiburn** tool. You need to configure burning parameters in the **bundle.json** file of the distribution.
```
"scripts": {
"flash": "{$DEP_HIBURN}/hiburn"
},
```
Set the path of the **hiburn** tool and set burning parameters. For details, see the **hiburn** tool guide.
```
hpm config set DEP_HIBURN {hiburn_path}
hpm run flash
```
>![](../public_sys-resources/icon-note.gif) **NOTE:**
>The preceding example describes only how to define the **bundle.json** file. The burning tool is subject to the actual development board.
en/device-dev/bundles/bundles-guide-overview.md 已删除 100644 → 0
浏览文件 @ f0336962
# Overview<a name="EN-US_TOPIC_0000001051452100"></a>
This section describes the bundle-specific concepts in HarmonyOS. It uses an example to step you through how to create, develop, build, release, and install a bundle using the **hpm-cli** tool.
## Bundle<a name="section196713235514"></a>
A bundle is a term used in HarmonyOS to indicate a distribution. A bundle is equivalent to a package and it usually contains the following contents:
- Distributed binary file \(binary type\)
- Distributed source code file \(source code/code snippet type\)
- Build script \(distribution type\)
- Bundle description files:
- **bundle.json**: metadata declaration \(name, version, dependency, etc.\)
- **LICENSE**: license agreement
- **README.md**: readme file
- **CHANGELOG.md**: change log \(optional\)
>![](../public_sys-resources/icon-note.gif) **NOTE:**
>Bundles can be classified into the following types: binary, source code, code snippet, template, plug-in, distribution, and so on. A bundle can depend on other bundles. The dependency relationship can be represented by a directed acyclic graph \(DAG\).
After you release a bundle on the [HPM](https://hpm.harmonyos.com/#/en/home) platform, other developers can download, install, and use the bundle through the HarmonyOS Package Manager \(hpm\).
A bundle must be uniquely named in the format **@scope/name** in the namespace. Independent evolution is supported for each bundle.
## Distribution<a name="section155387501033"></a>
A distribution is a complete HarmonyOS release that integrates various bundles, including drivers, kernels, frameworks, and applications. A distribution can also be distributed on the [HPM](https://hpm.harmonyos.com/#/en/home) platform through bundles.
>![](../public_sys-resources/icon-note.gif) **NOTE:**
>The metadata of a distribution describes only the dependent bundles and build script compilation methods. It does not cover binary images of the distribution. When downloading a distribution, you also need to download the dependent bundles. You can obtain the system image file for burning only after finishing installation and compilation.
>A distribution is inheritable. Specifically, you can add bundles to or delete bundles from an existing distribution to create your own distribution.
**Figure 1** Relationship between bundles and a distribution<a name="fig85033524124"></a>
![](figure/bundle-distribution.png)
en/device-dev/bundles/bundles-guide-prepare.md 已删除 100644 → 0
浏览文件 @ f0336962
# Installing hpm-cli Tool<a name="EN-US_TOPIC_0000001051770836"></a>
To develop a bundle, you first need to install the HarmonyOS Package Manager \(hpm\), a cross-platform command line tool developed based on Node.js. To run the hpm, you need to install Node.js, and then install the hpm using the Node Package Manager \(npm\).
## Installing Node.js and hpm<a name="section106591616205311"></a>
1. Install **Node.js**.
Download **Node.js** from its official website and install it on your local PC.
You are advised to install [Node.js](https://nodejs.org/) 12.x \(including npm 6.14.4\) or a later version \(12.13.0 or later is recommended\).
2. Install the **hpm-cli** tool using **npm** delivered with **Node.js**. Run the following command:
```
npm install -g @ohos/hpm-cli
```
3. Run the following command to check whether the installation is successful. If an hpm version is displayed, the installation is successful.
```
hpm -V or hpm --version
```
4. \(Optional\) Run the following command to upgrade the hpm version if needed:
```
npm update -g @ohos/hpm-cli
```
## \(Optional\) Configuring hpm<a name="section71821165412"></a>
After the **hpm-cli** tool is installed, run the following command to view the hpm configuration if you need to modify the configuration information, such as proxy and shell:
```
hpm config
```
Default hpm configurations are displayed upon successful command execution. You can modify the default configurations as required. The following lists common hpm configurations:
```
registry = https://hpm.harmonyos.com
### login Settings
# loginUser = invitation_code
#### Path Settings
shellPath = C:\WINDOWS\System32\cmd.exe
# shellPath = C:\Program Files\Git\bin\sh.exe
# globalRepo = C:\Users\username\.hpm\global
#### Network Settings
# no_proxy = *.server.com
# http_proxy = http://user:pwd@proxy_server:port
# https_proxy = http://user:pwd@proxy_server:port
# strictSsl = true
#### Other Settings
# privateSupport = true|false
# ignoreBundles = @ohos/llvm,@ohos/gn,
# OSPlatform = Auto|linux|darwin|win32
```
For details about **hpm-cli** commands, see [HPM Commands](bundles-guide-overview.md).
## Downloading OpenHarmony Code<a name="section102338221707"></a>
For details, see [Source Code Acquisition](../get-code/sourcecode-acquire.md).
en/device-dev/bundles/bundles-guide.md 已删除 100644 → 0
浏览文件 @ f0336962
# HPM Bundle Development Guidelines<a name="EN-US_TOPIC_0000001157319417"></a>
- **[Overview](bundles-guide-overview.md)**
- **[Installing hpm-cli Tool](bundles-guide-prepare.md)**
- **[Developing Bundles](bundles-guide-develop.md)**
en/device-dev/bundles/bundles-standard-rules.md 已删除 100644 → 0
浏览文件 @ f0336962
# HPM Bundle Development Specifications<a name="EN-US_TOPIC_0000001051452141"></a>
## Overview<a name="section1725818533344"></a>
This document describes the basic concepts of a bundle and how to define it in compliance with specifications.
### Definition<a name="section4821219183514"></a>
OpenHarmony software is developed on a per-bundle basis. In terms of the operating system, all software running on OpenHarmony are bundles. Generally, bundles are classified into the following types based on their application scopes:
- Board-level bundles: device hardware-specific bundles, such as **board**, **arch**, and **mcu**
- System-level bundles: a set of bundles with independent features, such as the kernel, file system, and framework
- Application-level bundles: applications that provide services to users, such as **wifi\_iot** and **ip\_camera**
Bundles are designed for reuse purposes. Any reusable modules can be defined as bundles. They are classified into the following types based on their forms:
- Source code
- Binary system
- Code snippet
- Distribution
### Bundle Division Rules<a name="section1089794263513"></a>
In principle, bundles should be grouped at a fine-grained granularity as much as possible to achieve maximum reuse. The following factors are taken into account regarding bundle division:
- Independence: Bundles provide relatively independent features and can be independently built. Each bundle is capable of providing its own APIs and services for external systems.
- Coupling: If a bundle must depend on another bundle to provide services, they can be coupled to one bundle.
- Correlation: If a group of bundles jointly implement a feature, and if other bundles never depend on them, the group of bundles can be combined into one bundle.
### Bundle Dependency<a name="section25701647163710"></a>
A bundle dependency can be mandatory or optional.
- Mandatory dependency: If bundle A must depend on bundle B to implement a feature \(the APIs or services specific to bundle B must be invoked\), bundle B is a mandatory dependency of bundle A.
- Optional dependency: If bundle C or bundle D is required for bundle A to implement a feature and bundle C and bundle D are interchangeable, bundle C and bundle D are optional dependencies of bundle A.
## Bundle Composition<a name="section185538333914"></a>
A bundle contains the following:
- **src** directory for storing code files or code library of the bundle
- **ohos\_bundles** folder for storing dependent bundles \(It is automatically generated during bundle installation, without the need to submit to the code library.\)
- **README.md** file for describing the bundle
- **bundle.json** file for declaring metadata of the bundle
- **LICENSE** file for open-source code
```
my-bundle
|_ohos_bundles
|_src
|_bundle.json
|_README.md
|_LICENSE
```
### Code Files<a name="section8431268393"></a>
Bundle code files are the same as those in a common code directory. The only difference lies in the open APIs \(declared in header files\) of a bundle, which are likely to be referenced by other bundles and need to be declared in **dirs** of **bundle.json**.
### README File<a name="section168121548173914"></a>
**README.md** is a bundle self-description file using the markdown syntax. For details, see [Syntax Reference](https://www.markdownguide.org/getting-started/).
To help you easily find and use the desired bundle on the HarmonyOS Package Manager \(HPM\) platform, a **README** file is provided in the root directory of each bundle.
The **README** file may include instructions on how to install, configure, and use the instance code in the bundle, as well as any other information helpful to you.
The **README** file is available in the bundle details page of the HPM platform.
### Metadata Description File<a name="section7107181819406"></a>
The **bundle.json** file describes the metadata of a bundle. Each bundle has its own **bundle.json** file.
```
{
"name": "@myorg/demo-bundle",
"version": "1.0.0",
"license": "MIT",
"description": "bundle description",
"keywords": ["hos"],
"tags": ["applications", "drivers"],
"author": {"name":"","email":"","url":""},
"contributors":[{"name":"","email":"","url":""},{"name":"","email":"","url":""}],
"homepage": "http://www.foo.bar.com",
"repository": "https://git@gitee.com:foo/bar.git",
"publishAs": "code-segment",
"segment":{
"destPath":"/the/dest/path"
},
"dirs": {
"src": ["src/**/*.c"],
"headers": ["headers/**/*.h"],
"bin": ["bin/**/*.o"]
},
"scripts": {
"build": "make"
},
"envs": {},
"ohos": {
"os": "2.0.0",
"board": "hi3516",
"kernel": "liteos-a"
},
"rom": "10240",
"ram": "1024",
"dependencies": {
"@myorg/net":"1.0.0"
}
}
```
Each **bundle.json** file has the following fields:
- **name**: a bundle name, which starts with @ and is separated by /, for example, **@myorg/mybundle**
- **version**: a bundle version number, for example, 1.0.0. The version number must comply with the Semantic Versioning Specification \(SemVer\) standards.
- **description**: a brief description of a bundle
- **dependencies**: bundles on which this bundle depends.
- **envs**: parameters required for bundle compilation, including global parameters and dependency parameters.
- **scripts**: commands executable to a bundle, such as commands for compiling, building, testing, and burning
- **publishAs**: bundle publishing type, which can be **source**, **binary**, **distribution**, or **code-segment**
- **segment**: destination path of the code-segment bundle. That is, the destination path of the files contained in the bundle package after the bundle is installed.
- **dirs**: directory structure \(such as the header file\) generated for publishing
- **ram&rom**: statistical information about the estimated read-only memory \(ROM\) and random access memory \(RAM\) usage
- **ohos**: mappings among OpenHarmony versions, development boards, and kernels, separated by commas \(,\).
- Extended information: author, home page, code repository, license, tags, and keywords
- **base** \(only for a distribution\): a base distribution which others inherit from.
## Bundle Management<a name="section32061634104110"></a>
### Dependency<a name="section791115242423"></a>
A basic **bundle.json** file needs to be enriched by bundle dependencies to implement more complex features. Bundle names and version numbers should be defined in the **dependencies** field of **bundle.json**.
```
{
"name": "my-bundle",
"version": "1.0.0",
"dependencies": {
"net": "1.0.0"
}
}
```
In the preceding example, the **my-bundle** bundle depends on the **net 1.0.0** bundle. After you globally install the hpm-cli tool, run the following command to obtain bundle dependencies from the remote repository:
```
hpm install
```
Bundle dependencies are then stored in the **ohos\_bundles** folder in the root directory of the current bundle. A tree structure illustrating the bundle and its dependencies will be generated. You need to run the following command in the root directory of the bundle:
```
username@server MINGW64 /f/showcase/demo/demo
$ hpm list
+--demo@1.0.0
| +--@example/media@1.0.2
| +--@demo/sport_hi3518ev300_liteos_a@1.0.0
| | +--@demo/app@4.0.1
| | | +--@demo/build@4.0.1
| | | +--@demo/arm_harmonyeabi_gcc@4.0.0
| | +--@demo/liteos_a@4.0.0
| | | +--@demo/third_party_fatfs@4.0.0
| | | +--@demo/arm_harmonyeabi_gcc@4.0.0
| | +--@demo/init@4.0.0
| | +--@demo/dist_tools@4.0.0
```
Alternatively, you can run the following command to view the dependencies of the current bundle in a visualized way:
```
hpm ui
```
A web service is started on the local host \(by default, the browser is open and the project page is displayed\). Click the project dependency icon on the sidebar. The list of dependent bundles is displayed. Click the button on the right to switch to the tree view. The bundle dependencies are displayed as shown in the following figure.
**Figure 1** Bundle dependencies<a name="fig4306113315312"></a>
![](figure/en-us_image_0000001173313501.png)
### HPM Command Reference<a name="section1183205411429"></a>
You can use the hpm-cli tool to manage the lifecycle of a bundle. The following table describes available HPM commands. \(You can run the **hpm -h** command to get the command details\).
**Table 1** HPM commands
<a name="table10510164515371"></a>
<table><thead align="left"><tr id="row125101745103718"><th class="cellrowborder" valign="top" width="20.95209520952095%" id="mcps1.2.4.1.1"><p id="p1451014454371"><a name="p1451014454371"></a><a name="p1451014454371"></a>Function</p>
</th>
<th class="cellrowborder" valign="top" width="30.623062306230626%" id="mcps1.2.4.1.2"><p id="p17510144553716"><a name="p17510144553716"></a><a name="p17510144553716"></a>Command Line</p>
</th>
<th class="cellrowborder" valign="top" width="48.42484248424842%" id="mcps1.2.4.1.3"><p id="p65102452371"><a name="p65102452371"></a><a name="p65102452371"></a>Description</p>
</th>
</tr>
</thead>
<tbody><tr id="row25106453375"><td class="cellrowborder" valign="top" width="20.95209520952095%" headers="mcps1.2.4.1.1 "><p id="p151044514378"><a name="p151044514378"></a><a name="p151044514378"></a>Querying version information</p>
</td>
<td class="cellrowborder" valign="top" width="30.623062306230626%" headers="mcps1.2.4.1.2 "><p id="p1653795113472"><a name="p1653795113472"></a><a name="p1653795113472"></a><strong id="b23722045105918"><a name="b23722045105918"></a><a name="b23722045105918"></a>hpm -V</strong> or <strong id="b1843564817597"><a name="b1843564817597"></a><a name="b1843564817597"></a>hpm --version</strong></p>
</td>
<td class="cellrowborder" valign="top" width="48.42484248424842%" headers="mcps1.2.4.1.3 "><p id="p399295684713"><a name="p399295684713"></a><a name="p399295684713"></a>Displays the <strong id="b10433453155910"><a name="b10433453155910"></a><a name="b10433453155910"></a>hpm-cli</strong> version number.</p>
</td>
</tr>
<tr id="row651017455374"><td class="cellrowborder" rowspan="2" align="left" valign="top" width="20.95209520952095%" headers="mcps1.2.4.1.1 "><p id="p551054516372"><a name="p551054516372"></a><a name="p551054516372"></a>Querying help information</p>
</td>
<td class="cellrowborder" valign="top" width="30.623062306230626%" headers="mcps1.2.4.1.2 "><p id="p18648167124812"><a name="p18648167124812"></a><a name="p18648167124812"></a><strong id="b14121331016"><a name="b14121331016"></a><a name="b14121331016"></a>hpm -h</strong> or <strong id="b78431961011"><a name="b78431961011"></a><a name="b78431961011"></a>hpm --version</strong></p>
</td>
<td class="cellrowborder" valign="top" width="48.42484248424842%" headers="mcps1.2.4.1.3 "><p id="p1464811794817"><a name="p1464811794817"></a><a name="p1464811794817"></a>Displays the command list and help information.</p>
</td>
</tr>
<tr id="row1751016452379"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p16778111111487"><a name="p16778111111487"></a><a name="p16778111111487"></a>hpm -h</p>
</td>
<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p1877811154818"><a name="p1877811154818"></a><a name="p1877811154818"></a>Displays command help information.</p>
</td>
</tr>
<tr id="row2511945123715"><td class="cellrowborder" rowspan="2" valign="top" width="20.95209520952095%" headers="mcps1.2.4.1.1 "><p id="p3955174864810"><a name="p3955174864810"></a><a name="p3955174864810"></a>Creating a project</p>
<p id="p14511184518374"><a name="p14511184518374"></a><a name="p14511184518374"></a></p>
</td>
<td class="cellrowborder" valign="top" width="30.623062306230626%" headers="mcps1.2.4.1.2 "><p id="p2046811558481"><a name="p2046811558481"></a><a name="p2046811558481"></a>hpm init bundle</p>
</td>
<td class="cellrowborder" valign="top" width="48.42484248424842%" headers="mcps1.2.4.1.3 "><p id="p1646818557481"><a name="p1646818557481"></a><a name="p1646818557481"></a>Create a bundle project.</p>
</td>
</tr>
<tr id="row351184593713"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p18991313496"><a name="p18991313496"></a><a name="p18991313496"></a>hpm init -t template</p>
</td>
<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p109912104911"><a name="p109912104911"></a><a name="p109912104911"></a>Creates a scaffolding project from a template.</p>
</td>
</tr>
<tr id="row1751164511374"><td class="cellrowborder" rowspan="2" valign="top" width="20.95209520952095%" headers="mcps1.2.4.1.1 "><p id="p1351111454374"><a name="p1351111454374"></a><a name="p1351111454374"></a>Installing bundles</p>
<p id="p251144513715"><a name="p251144513715"></a><a name="p251144513715"></a></p>
</td>
<td class="cellrowborder" valign="top" width="30.623062306230626%" headers="mcps1.2.4.1.2 "><p id="p8896182914913"><a name="p8896182914913"></a><a name="p8896182914913"></a><strong id="b4390361468"><a name="b4390361468"></a><a name="b4390361468"></a>hpm install</strong> or <strong id="b1214217411867"><a name="b1214217411867"></a><a name="b1214217411867"></a>hpm i</strong></p>
</td>
<td class="cellrowborder" valign="top" width="48.42484248424842%" headers="mcps1.2.4.1.3 "><p id="p1289692919493"><a name="p1289692919493"></a><a name="p1289692919493"></a>Installs dependent bundles in the <strong id="b10937442619"><a name="b10937442619"></a><a name="b10937442619"></a>bundle.json</strong> file.</p>
</td>
</tr>
<tr id="row15511194563712"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p17917436134911"><a name="p17917436134911"></a><a name="p17917436134911"></a>hpm install bundle@version</p>
</td>
<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p1891723611494"><a name="p1891723611494"></a><a name="p1891723611494"></a>Installs bundles of a specified version.</p>
</td>
</tr>
<tr id="row21051110155011"><td class="cellrowborder" rowspan="2" valign="top" width="20.95209520952095%" headers="mcps1.2.4.1.1 "><p id="p1630384435010"><a name="p1630384435010"></a><a name="p1630384435010"></a>Uninstalling bundles</p>
<p id="p83417161509"><a name="p83417161509"></a><a name="p83417161509"></a></p>
</td>
<td class="cellrowborder" valign="top" width="30.623062306230626%" headers="mcps1.2.4.1.2 "><p id="p288195017502"><a name="p288195017502"></a><a name="p288195017502"></a>hpm uninstall bundle</p>
</td>
<td class="cellrowborder" valign="top" width="48.42484248424842%" headers="mcps1.2.4.1.3 "><p id="p2088450165014"><a name="p2088450165014"></a><a name="p2088450165014"></a>Uninstalls dependent bundles.</p>
</td>
</tr>
<tr id="row73341617507"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p934161613508"><a name="p934161613508"></a><a name="p934161613508"></a><strong id="b958269375"><a name="b958269375"></a><a name="b958269375"></a>hpm remove</strong> or <strong id="b32697125714"><a name="b32697125714"></a><a name="b32697125714"></a>hpm rm bundlename</strong></p>
</td>
<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p234111685016"><a name="p234111685016"></a><a name="p234111685016"></a>Removes dependent bundles.</p>
</td>
</tr>
<tr id="row166449214501"><td class="cellrowborder" rowspan="2" valign="top" width="20.95209520952095%" headers="mcps1.2.4.1.1 "><p id="p8645421125016"><a name="p8645421125016"></a><a name="p8645421125016"></a>Viewing information</p>
<p id="p12645202115014"><a name="p12645202115014"></a><a name="p12645202115014"></a></p>
</td>
<td class="cellrowborder" valign="top" width="30.623062306230626%" headers="mcps1.2.4.1.2 "><p id="p679412535211"><a name="p679412535211"></a><a name="p679412535211"></a><strong id="b12958426476"><a name="b12958426476"></a><a name="b12958426476"></a>hpm list</strong> or <strong id="b168628296714"><a name="b168628296714"></a><a name="b168628296714"></a>hpm ls</strong></p>
</td>
<td class="cellrowborder" valign="top" width="48.42484248424842%" headers="mcps1.2.4.1.3 "><p id="p07941451526"><a name="p07941451526"></a><a name="p07941451526"></a>Displays the bundle tree of available bundles and distributions.</p>
</td>
</tr>
<tr id="row1764552105017"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p035818131525"><a name="p035818131525"></a><a name="p035818131525"></a>hpm dependencies</p>
</td>
<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p19358413135217"><a name="p19358413135217"></a><a name="p19358413135217"></a>Generates the dependency relationship data of a bundle or distribution. (This command is also integrated in the HPM UI to display the bundle dependencies intuitively.)</p>
</td>
</tr>
<tr id="row1553428145020"><td class="cellrowborder" valign="top" width="20.95209520952095%" headers="mcps1.2.4.1.1 "><p id="p353202845014"><a name="p353202845014"></a><a name="p353202845014"></a>Searching for bundles</p>
</td>
<td class="cellrowborder" valign="top" width="30.623062306230626%" headers="mcps1.2.4.1.2 "><p id="p1423903005211"><a name="p1423903005211"></a><a name="p1423903005211"></a>hpm search name</p>
</td>
<td class="cellrowborder" valign="top" width="48.42484248424842%" headers="mcps1.2.4.1.3 "><p id="p17239163018524"><a name="p17239163018524"></a><a name="p17239163018524"></a>Searches for bundles. <strong id="b13869134316718"><a name="b13869134316718"></a><a name="b13869134316718"></a>--json</strong> is used to specify the search result in JSON format, and <strong id="b168767431673"><a name="b168767431673"></a><a name="b168767431673"></a>-type</strong> is used to set the target type, which can be <strong id="b1187754318710"><a name="b1187754318710"></a><a name="b1187754318710"></a>bundle</strong>, <strong id="b1877743570"><a name="b1877743570"></a><a name="b1877743570"></a>distribution</strong>, or <strong id="b787715431774"><a name="b787715431774"></a><a name="b787715431774"></a>code-segment</strong>.</p>
</td>
</tr>
<tr id="row135482855018"><td class="cellrowborder" rowspan="2" valign="top" width="20.95209520952095%" headers="mcps1.2.4.1.1 "><p id="p38201311174016"><a name="p38201311174016"></a><a name="p38201311174016"></a>Setting HPM configuration items</p>
</td>
<td class="cellrowborder" valign="top" width="30.623062306230626%" headers="mcps1.2.4.1.2 "><p id="p279915013522"><a name="p279915013522"></a><a name="p279915013522"></a>hpm config set key value</p>
</td>
<td class="cellrowborder" valign="top" width="48.42484248424842%" headers="mcps1.2.4.1.3 "><p id="p157991450205211"><a name="p157991450205211"></a><a name="p157991450205211"></a>Sets configuration items, such as the server address and network proxy.</p>
</td>
</tr>
<tr id="row454172810509"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p111125615215"><a name="p111125615215"></a><a name="p111125615215"></a>hpm config delete key</p>
</td>
<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p171156105215"><a name="p171156105215"></a><a name="p171156105215"></a>Deletes configurations.</p>
</td>
</tr>
<tr id="row3925233115011"><td class="cellrowborder" rowspan="2" valign="top" width="20.95209520952095%" headers="mcps1.2.4.1.1 "><p id="p1250314020555"><a name="p1250314020555"></a><a name="p1250314020555"></a>Updating bundle versions</p>
<p id="p59251633105018"><a name="p59251633105018"></a><a name="p59251633105018"></a></p>
</td>
<td class="cellrowborder" valign="top" width="30.623062306230626%" headers="mcps1.2.4.1.2 "><p id="p1127981305516"><a name="p1127981305516"></a><a name="p1127981305516"></a>hpm update</p>
</td>
<td class="cellrowborder" valign="top" width="48.42484248424842%" headers="mcps1.2.4.1.3 "><p id="p427971311555"><a name="p427971311555"></a><a name="p427971311555"></a>Updates the versions of dependent bundles.</p>
</td>
</tr>
<tr id="row692503385015"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p627961317557"><a name="p627961317557"></a><a name="p627961317557"></a>hpm check-update</p>
</td>
<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p3279121315557"><a name="p3279121315557"></a><a name="p3279121315557"></a>Checks whether version updates are available to dependent bundles.</p>
</td>
</tr>
<tr id="row1925173385019"><td class="cellrowborder" rowspan="2" valign="top" width="20.95209520952095%" headers="mcps1.2.4.1.1 "><p id="p2925133305014"><a name="p2925133305014"></a><a name="p2925133305014"></a>Building</p>
<p id="p692515335501"><a name="p692515335501"></a><a name="p692515335501"></a></p>
</td>
<td class="cellrowborder" valign="top" width="30.623062306230626%" headers="mcps1.2.4.1.2 "><p id="p2058919655611"><a name="p2058919655611"></a><a name="p2058919655611"></a>hpm build</p>
</td>
<td class="cellrowborder" valign="top" width="48.42484248424842%" headers="mcps1.2.4.1.3 "><p id="p1958920625619"><a name="p1958920625619"></a><a name="p1958920625619"></a>Builds a bundle or distribution.</p>
</td>
</tr>
<tr id="row18925233115016"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p1958912618563"><a name="p1958912618563"></a><a name="p1958912618563"></a>hpm dist</p>
</td>
<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p2058936115611"><a name="p2058936115611"></a><a name="p2058936115611"></a>Builds a distribution. The build depends on the <strong id="b1993772316398"><a name="b1993772316398"></a><a name="b1993772316398"></a>dist</strong> script in <strong id="b10517183118398"><a name="b10517183118398"></a><a name="b10517183118398"></a>scripts</strong> of <strong id="b52387374392"><a name="b52387374392"></a><a name="b52387374392"></a>bundle.json</strong>.</p>
</td>
</tr>
<tr id="row59261233155013"><td class="cellrowborder" valign="top" width="20.95209520952095%" headers="mcps1.2.4.1.1 "><p id="p3926123305011"><a name="p3926123305011"></a><a name="p3926123305011"></a>Packing</p>
</td>
<td class="cellrowborder" valign="top" width="30.623062306230626%" headers="mcps1.2.4.1.2 "><p id="p1785810219574"><a name="p1785810219574"></a><a name="p1785810219574"></a>hpm pack</p>
</td>
<td class="cellrowborder" valign="top" width="48.42484248424842%" headers="mcps1.2.4.1.3 "><p id="p1485872165714"><a name="p1485872165714"></a><a name="p1485872165714"></a>Packs dependencies of local bundles.</p>
</td>
</tr>
<tr id="row1592653305016"><td class="cellrowborder" valign="top" width="20.95209520952095%" headers="mcps1.2.4.1.1 "><p id="p84251810125716"><a name="p84251810125716"></a><a name="p84251810125716"></a>Burning</p>
</td>
<td class="cellrowborder" valign="top" width="30.623062306230626%" headers="mcps1.2.4.1.2 "><p id="p7973616175716"><a name="p7973616175716"></a><a name="p7973616175716"></a>hpm run flash</p>
</td>
<td class="cellrowborder" valign="top" width="48.42484248424842%" headers="mcps1.2.4.1.3 "><p id="p20973111612575"><a name="p20973111612575"></a><a name="p20973111612575"></a>Burns the firmware. The firmware burning depends on the <strong id="b1475618382812"><a name="b1475618382812"></a><a name="b1475618382812"></a>flash</strong> script in <strong id="b1176220383816"><a name="b1176220383816"></a><a name="b1176220383816"></a>scripts</strong> of <strong id="b1276218381784"><a name="b1276218381784"></a><a name="b1276218381784"></a>bundle.json</strong>.</p>
</td>
</tr>
<tr id="row992615339504"><td class="cellrowborder" valign="top" width="20.95209520952095%" headers="mcps1.2.4.1.1 "><p id="p1225172310576"><a name="p1225172310576"></a><a name="p1225172310576"></a>Publishing</p>
</td>
<td class="cellrowborder" valign="top" width="30.623062306230626%" headers="mcps1.2.4.1.2 "><p id="p198081455105712"><a name="p198081455105712"></a><a name="p198081455105712"></a>hpm publish</p>
</td>
<td class="cellrowborder" valign="top" width="48.42484248424842%" headers="mcps1.2.4.1.3 "><p id="p880885516574"><a name="p880885516574"></a><a name="p880885516574"></a>Publishes a bundle, which must be unique in the repository and has a unique version. (An account is required for login.)</p>
</td>
</tr>
<tr id="row5926333135014"><td class="cellrowborder" valign="top" width="20.95209520952095%" headers="mcps1.2.4.1.1 "><p id="p39267336504"><a name="p39267336504"></a><a name="p39267336504"></a>Running extended commands</p>
</td>
<td class="cellrowborder" valign="top" width="30.623062306230626%" headers="mcps1.2.4.1.2 "><p id="p9933172588"><a name="p9933172588"></a><a name="p9933172588"></a>hpm run</p>
</td>
<td class="cellrowborder" valign="top" width="48.42484248424842%" headers="mcps1.2.4.1.3 "><p id="p18933476584"><a name="p18933476584"></a><a name="p18933476584"></a>Runs the commands in <strong id="b32841491983"><a name="b32841491983"></a><a name="b32841491983"></a>scripts</strong> defined in <strong id="b1529217495817"><a name="b1529217495817"></a><a name="b1529217495817"></a>bundle.json</strong>. Multiple commands can be executed at a time by using <strong id="b6292949385"><a name="b6292949385"></a><a name="b6292949385"></a>&amp;&amp;</strong>.</p>
</td>
</tr>
<tr id="row51431053122610"><td class="cellrowborder" valign="top" width="20.95209520952095%" headers="mcps1.2.4.1.1 "><p id="p7143155332618"><a name="p7143155332618"></a><a name="p7143155332618"></a>Decompressing</p>
</td>
<td class="cellrowborder" valign="top" width="30.623062306230626%" headers="mcps1.2.4.1.2 "><p id="p71438531269"><a name="p71438531269"></a><a name="p71438531269"></a>hpm extract</p>
</td>
<td class="cellrowborder" valign="top" width="48.42484248424842%" headers="mcps1.2.4.1.3 "><p id="p1214317539267"><a name="p1214317539267"></a><a name="p1214317539267"></a>Decompresses files in zip, tar, tgz, or .tar.gz format.</p>
</td>
</tr>
<tr id="row2144175352615"><td class="cellrowborder" valign="top" width="20.95209520952095%" headers="mcps1.2.4.1.1 "><p id="p014425315267"><a name="p014425315267"></a><a name="p014425315267"></a>Restarting GUI</p>
</td>
<td class="cellrowborder" valign="top" width="30.623062306230626%" headers="mcps1.2.4.1.2 "><p id="p614411533260"><a name="p614411533260"></a><a name="p614411533260"></a>hpm ui</p>
</td>
<td class="cellrowborder" valign="top" width="48.42484248424842%" headers="mcps1.2.4.1.3 "><p id="p13144135382611"><a name="p13144135382611"></a><a name="p13144135382611"></a>Starts the HPM UI locally. You can use the <strong id="b693910764616"><a name="b693910764616"></a><a name="b693910764616"></a>-p</strong> parameter to specify a port. On the Windows platform, the default browser is used to open the HPM UI.</p>
</td>
</tr>
<tr id="row616119173278"><td class="cellrowborder" valign="top" width="20.95209520952095%" headers="mcps1.2.4.1.1 "><p id="p1716118170279"><a name="p1716118170279"></a><a name="p1716118170279"></a>Changing language</p>
</td>
<td class="cellrowborder" valign="top" width="30.623062306230626%" headers="mcps1.2.4.1.2 "><p id="p171616172277"><a name="p171616172277"></a><a name="p171616172277"></a>hpm lang</p>
</td>
<td class="cellrowborder" valign="top" width="48.42484248424842%" headers="mcps1.2.4.1.3 "><p id="p1216121752712"><a name="p1216121752712"></a><a name="p1216121752712"></a>Alternates between Chinese and English on the CLI and UI.</p>
</td>
</tr>
<tr id="row81611717182720"><td class="cellrowborder" valign="top" width="20.95209520952095%" headers="mcps1.2.4.1.1 "><p id="p1816181792712"><a name="p1816181792712"></a><a name="p1816181792712"></a>Converting to HPM format</p>
</td>
<td class="cellrowborder" valign="top" width="30.623062306230626%" headers="mcps1.2.4.1.2 "><p id="p616191713276"><a name="p616191713276"></a><a name="p616191713276"></a>hpm x2h</p>
</td>
<td class="cellrowborder" valign="top" width="48.42484248424842%" headers="mcps1.2.4.1.3 "><p id="p1116121712711"><a name="p1116121712711"></a><a name="p1116121712711"></a>Converts a Maven or NPM package to an HPM package and publishes it to the HPM.</p>
</td>
</tr>
<tr id="row1177713643711"><td class="cellrowborder" valign="top" width="20.95209520952095%" headers="mcps1.2.4.1.1 "><p id="p877719363374"><a name="p877719363374"></a><a name="p877719363374"></a>Code segment restoration or cleanup</p>
</td>
<td class="cellrowborder" valign="top" width="30.623062306230626%" headers="mcps1.2.4.1.2 "><p id="p6778236153710"><a name="p6778236153710"></a><a name="p6778236153710"></a>hpm code clean|restore</p>
</td>
<td class="cellrowborder" valign="top" width="48.42484248424842%" headers="mcps1.2.4.1.3 "><p id="p1277843613376"><a name="p1277843613376"></a><a name="p1277843613376"></a>Clears or restores the dependent code segment (code-segment). That is, copy or delete the code segment based on <strong id="b152081043103011"><a name="b152081043103011"></a><a name="b152081043103011"></a>segment.destPath</strong>.</p>
</td>
</tr>
<tr id="row122864915206"><td class="cellrowborder" valign="top" width="20.95209520952095%" headers="mcps1.2.4.1.1 "><p id="p1529124912207"><a name="p1529124912207"></a><a name="p1529124912207"></a>Generating a key</p>
</td>
<td class="cellrowborder" valign="top" width="30.623062306230626%" headers="mcps1.2.4.1.2 "><p id="p9291492204"><a name="p9291492204"></a><a name="p9291492204"></a>hpm gen-keys</p>
</td>
<td class="cellrowborder" valign="top" width="48.42484248424842%" headers="mcps1.2.4.1.3 "><p id="p429249182012"><a name="p429249182012"></a><a name="p429249182012"></a>Generates a public-private key pair and configures the public key on the HPM server, which enables password-free <strong id="b166318457106"><a name="b166318457106"></a><a name="b166318457106"></a>hpm-cli</strong> login for bundle publishing.</p>
</td>
</tr>
<tr id="row3556450102011"><td class="cellrowborder" valign="top" width="20.95209520952095%" headers="mcps1.2.4.1.1 "><p id="p35561850172015"><a name="p35561850172015"></a><a name="p35561850172015"></a>Generating third-party open source notice</p>
</td>
<td class="cellrowborder" valign="top" width="30.623062306230626%" headers="mcps1.2.4.1.2 "><p id="p1155625018209"><a name="p1155625018209"></a><a name="p1155625018209"></a>hpm gen-notice</p>
</td>
<td class="cellrowborder" valign="top" width="48.42484248424842%" headers="mcps1.2.4.1.3 "><p id="p11557175015205"><a name="p11557175015205"></a><a name="p11557175015205"></a>Generates a file providing the notice on third-party open source by combining the description of each bundle.</p>
</td>
</tr>
</tbody>
</table>
## Bundle Version<a name="section12612142864316"></a>
### Version Number Naming Specifications<a name="section1487612416432"></a>
Each version name allows only lowercase letters, which can be separated by hyphens \(-\) or underscores \(\_\). For example, **bundle** and **my\_bundle** are allowed.
A bundle version number is in the format of _major version number_._minor version number_._revision version number_ or _major version number_._minor version number_._revision version number_-_pre-release version number_, for example, **1.0.0** and **1.0.0-beta**. For details, see [https://semver.org](https://semver.org/).
### Version Publishing<a name="section1548171014440"></a>
You should upload bundles to the remote repository so that your peers have an option to use them. You can run the following command to upload the bundles:
```
hpm publish
```
After this command is executed, the system checks the bundle dependencies and downloads the missing dependencies. If the bundles you uploaded are in binary, the system compiles the entire bundle, generates a binary file, packs the file, and uploads it. If the bundles you uploaded are in another format, the system packs the bundle file in compliance with the defined packing rules and then uploads the file.
Note: To publish a bundle, you need an HPM account for login. After logging in to the HPM platform, register with an organization and apply for authentication. After successful authentication, you will have the permission to publish the bundle.
## Distribution<a name="section1264139114413"></a>
A distribution refers to an image file of an executable OpenHarmony solution composed of a group of bundles. It contains many dependent bundles and provides scripts to illustrate how to compile and link these bundles.
Generally, a distribution does not require code but contains only the **bundle.json** description \(**publishAs** set to **distribution**\) and some compilation scripts.
As system-provided environment variables are required during distribution compiling, run the **dist** command in **scripts**.
```
{
"publishAs":"distribution",
"scripts": {
"dist": "script compile command"
}
}
```
Run the following command:
```
hpm dist
```
As it is rather complex to redefine the functionality of a distribution, OpenHarmony allows inheritance from a distribution so that you can make a tailored distribution based on the existing functionality. To inherit from a distribution, you need to define the **base** field in **bundle.json**.
```
{
"base": {
"name": "dist_wifi_iot",
"version": "1.0.0"
}
}
```
In this example, the current bundle inherits from the **Bundledist-wifi-iot 1.0.0** bundle of the distribution.
Each distribution consists of many dependent bundles, which are represented by the **dependencies** field in **bundle.json**. Some dependencies are mandatory, and others can be added or removed required. In the **bundle.json** file, bundle names prefixed with a question mark \(?\) represent optional dependent bundles. If you want to inherit from a distribution involving such bundles, you can remove them and then add other bundles.
```
{
"dependencies": {
"?my_bundle": "1.0.0"
}
}
```
In this example, **my\_bundle** is an optional dependent bundle that can be removed by using the keyword **excludes**.
```
{
"excludes": [ "my_bundle" ]
}
```
The removed **my-bundle** will not be involved in the build process. If you forcibly remove mandatory dependent bundles, an error message will be displayed.
## Environment Variables<a name="section15352105174512"></a>
During bundle compilation, system-provided environment variables are required to define the output and link the required binary files. These variables are injected into the context for executing scripts based on service requirements. Therefore, their values can be directly obtained from the scripts. The following environment variables are available:
Global variables are defined by the **envs** attribute in **bundle.json**. All dependent bundles can obtain the values of global variables.
```
{
"envs": {
"compileEnv": "arm"
}
}
```
Different parameters can be passed to bundles when introducing dependencies so that the compilation of dependent bundles can meet the requirements of the current bundle. The parameters defined in the dependencies can be obtained from the context for executing the corresponding scripts.
```
{
"dependencies": {
"my-bundle": {
"version": "1.0.0",
"mode": "debug"
}
}
}
```
When linking to a binary file, the bundle needs to know the file path regarding the dependencies. Therefore, the path \(as an environment variable\) is passed to the bundle for compiling.
The passed environment variable is in **DEP\__BundleName_** format, where **BundleName** indicates the name of the dependent bundle, for example, **DEP\_first\_bundle**.
Tags can be defined to group dependent bundles. You can obtain the path of a group of dependent bundles based on their tag. A tag starts with a number sign \(\#\) and is defined as follows:
```
{
"dependencies": {
"#tool": {
"first-bundle": "1.0.0",
"second-bundle": "1.0.0"
},
"#drivers": {
"xx-bundle": "1.0.0",
"yy-bundle": "1.0.0"
}
}
}
```
There are two fixed environment variables:
- **DEP\_OHOS\_BUNDLES**: path of the **ohos\_bundles** folder
- **DEP\_BUNDLE\_BASE**: path of the outermost bundle
en/device-dev/bundles/bundles.md 已删除 100644 → 0
浏览文件 @ f0336962
# Bundle Development<a name="EN-US_TOPIC_0000001111039520"></a>
- **[Bundle Development Specifications](bundles-standard-rules.md)**
- **[Development Guidelines](bundles-guide.md)**
- **[HPM User Guide](bundles-demo.md)**
en/device-dev/bundles/hpm-part-about.md 0 → 100644
浏览文件 @ 2b8d818c
# HPM Part Overview
This section describes the basic concepts related to HPM Part in OpenHarmony.
## Introduction to HPM Part
### HPM Part Category
An HPM Part is used as a distribution unit in OpenHarmony. There are two types of HPM Parts:
- **Part/Module-level HPM Part**: used to achieve module or part reusability. The distributed content can be source code or binary files. Generally, such an HPM Part corresponds to a code repository and is a release of the code repository.
- **Distribution-level HPM Part**: used to describe an OS distribution. It consists of a list of dependent parts and scripts for building the distribution. The distribution contains various components (such as the driver, kernel, framework, and applications) of a complete OS. The image generated after the build can be used for burning.
### HPM Part Composition
An HPM Part consists of two types of files: description file and content file.
The table below lists the description files.
**Table 1** Description files
| File Name| Description | Mandatory |
| -------- | -------- | -------- |
| bundle.json | Metadata declaration file| Yes|
| README.md | Readme file| Yes|
| LICENSE | License file| Yes|
| CHANGEME.md | Change log file| No|
The content files can be any of the following:
- Binary file of the distributed part
- Source code file of the distributed part
- Build script file
**Figure 1** Relationship between the part/module-level HPM Part and distribution-level HPM Part
![en-us_image_0000001195369804](figures/en-us_image_0000001195369804.png)
## Introduction to HPM
OpenHarmony Package Manager (HPM) is an open collaboration platform that connects consumers and providers. HPM Parts are objects managed by HPM.
Through this platform, the provider can publish HPM Parts and the consumer can download and use HPM Parts.
- The provider declares the attributes of an HPM Part and publishes it to the platform.
- The consumer declares the dependencies in the HPM Part of the specified version to obtain the required resources.
The HPM platform matches the requirements of the provider and consumer.
**Figure 2** HPM functions
![en-us_image_0000001240409717](figures/en-us_image_0000001240409717.png)
**HPM consists of the following:**
- **hpm-cli: a cross-platform command line tool released in [@ohos/hpm-cli](https://www.npmjs.com/package/@ohos/hpm-cli)**
The hpm-cli tool offers a series of commands for creating, building, installing, packing, running, and publishing HPM Parts. You can use these commands to manage the lifecycle of the HPM Parts.
- **[DevEco Marketplace](https://repo.harmonyos.com): a resource repository on the server**
On [DevEco Marketplace](https://repo.harmonyos.com), you can register, store, and search for HPM Parts by category. Each HPM Part has a page providing access to its readme file, dependencies, historical versions, change history, license, download volume, and source code repository address. You can publish HPM Parts to this resource repository.
en/device-dev/bundles/hpm-part-development.md 0 → 100644
浏览文件 @ 2b8d818c
# HPM Part Development
## HPM Part Development Overview
You can search for common development resources on [DevEco Marketplace](https://repo.harmonyos.com) and import required resources to your projects through dependencies. If you cannot find the desired resources there, develop the resources on your own and publish them in the form of an HPM Part. To develop HPM Parts, install the hpm-cli tool first.
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
> You are advised to perform the following operations on Ubuntu 18.04 or later.
## Installing hpm-cli
The hpm-cli tool is developed based on Node.js. Therefore, you must install Node.js and then use npm to install hpm-cli.
### Installing Node.js and hpm-cli
1. Install Node.js.
Download Node.js from its official website and install it on your local PC.
You are advised to install the latest LTS version (not earlier than 12.x) of [Node.js](https://nodejs.org/).
2. Install the hpm-cli tool using **npm** delivered with **Node.js**. Run the following command:
```
npm install -g @ohos/hpm-cli
```
3. Run the following command to check whether the installation is successful. If a hpm version is displayed, the installation is successful.
```
hpm -V or hpm --version
```
4. (Optional) Run the following command to update the hpm version if needed:
```
npm update -g @ohos/hpm-cli
```
### (Optional) Configuring hpm-cli
After hpm-cli is installed, run the following command to view the hpm configuration:
```
hpm config
```
The default hpm configuration is displayed upon successful command execution. You can modify the default configuration as required. The following lists the common hpm configuration:
```
registry = https://hpm.harmonyos.com
### login Settings
# loginUser = invitation_code
#### Path Settings
shellPath = C:\WINDOWS\System32\cmd.exe
# shellPath = C:\Program Files\Git\bin\sh.exe
# globalRepo = C:\Users\username\.hpm\global
#### Network Settings
# no_proxy = *.server.com
# http_proxy = http://user:pwd@proxy_server:port
# https_proxy = http://user:pwd@proxy_server:port
# strictSsl = true
#### Other Settings
# privateSupport = true|false
# ignoreBundles = @ohos/llvm,@ohos/gn,
# OSPlatform = Auto|linux|darwin|win32
```
## Creating an HPM Part
You can create an HPM Part by using a template or define an existing project as an HPM Part.
### Creating an HPM Part Using a Template
1. Run the following command to create a directory:
```
hpm init -t default mybundle
```
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
> -In the preceding command, **default** indicates that the **default** template is used. You can use another template such as **simple** or **dist**.
The generated directory structure is as follows:
```
/
├── headers # Header file (example)
│ └── main.h
└── src # Source code (example)
│ └─ main.c
├── bundle.json # Metadata declaration file
└── LICENSE # License
└── Makefile # Build description file (example)
└── README.md # Readme file
```
2. Write the code and build script of the HPM Part.
```
hpm init -t {templatename} -d {dir} {name}
```
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
> - -**t {templatename}** indicates the template name.
>
> - -**d {dir}** indicates the path for storing the HPM Part to be created.
>
> - **name** indicates the name of the HPM Part to be created.
The hpm-cli tool provides a few default templates. More templates are available on [DevEco Marketplace](https://repo.harmonyos.com). You can run the **hpm search -t template** command to search for a template stored on [DevEco Marketplace](https://repo.harmonyos.com).
![zh-cn_image_0000001217486680](figures/zh-cn_image_0000001217486680.png)
### Defining an Existing Project as an HPM Part
If you have a code project and need to distribute it on the HPM platform, run the following command in the project directory, for example, **mybundle2**:
```
hpm init
```
1. Enter an HPM Part name (**mybundle2** for example) and press **Enter**.
2. Enter the version and description. A **bundle.json** file will be generated in the current directory.
3. Open the **bundle.json** file.
```
$ hpm init
Your bundle will be created in directory ~\demo\mybundle2
? bundle name mybundle2
? version 1.0.0
...
Initialization finished.
```
4. Modify other information (such as the author, code repository, code directories, scripts, and dependencies) in **bundle.json**. An example is shown below:
```
{
"name": "mybundle2",
"version": "1.0.0",
"publishAs": "code-segment",
"dirs":{
".":["README.md"],
"src":["test.c"],
"header":["header/test.h" ],
"src/common":["src/common/foobar.txt"]
},
"scripts": {
"build": "make -${args}"
},
"dependencies": {
"@ohos/cjson": "^1.0.0",
"@ohos/foobar": "^1.2.0"
}
}
```
## Defining a Distribution
In the distribution metadata file, define the dependent HPM Parts and how to build and link them to generate image files.
The following uses the **bundle.json** file as an example. In this example, the **dist** command uses the **hb** framework.
```
{
"name": "@your/dist_name",
"version": "2.2.0",
"publishAs": "distribution",
"description": "describe it",
"scripts": {
"config_hb": "hb set -root $DEP_BUNDLE_BASE",
"dist": "PATH=/root/.local/bin:${DEP_OHOS_gn}:${DEP_OHOS_ninja}/ninja:${DEP_OHOS_llvm}/llvm/bin:${DEP_OHOS_hc_gen}/hc-gen:${PATH} && ./scripts/dist.sh"
},
"envs": {
"debug": false
},
"dirs": {
"scripts": "scripts/*"
},
"dependencies": {
"@ohos/build_lite": "2.2.0",
"@ohos/gn": "1.1.1",
"@ohos/llvm": "1.1.1",
"@ohos/hc_gen": "1.1.0",
"@ohos/ninja": "1.1.0",
......
},
"ohos": {
"os": "2.2-Beta",
"board": "hi3516",
"kernel": "liteos-a"
},
"keywords": [ "hispark", "hi3516" ],
"repository": "https://gitee.com/openharmony/your-project",
"license": "Apache V2"
}
```
## Building an HPM Part
If the code of an HPM Part can be independently built, you can configure the build tool and scripts to generate binary files.
The hpm-cli tool supports command integration so that you can select any build tool (such as make, gcc, and gn) suitable for your project. You only need to define the **build** command in **scripts** in the **bundle.json** file of your project, and then run the **hpm build** command to start the build.
### Defining the Build Script
This section describes how to build an executable file named **helloworld** in the **app** directory.
```
app
├── BUILD.gn
├── include
│ └── helloworld.h
└── src
└── helloworld.c
```
Create a **BUILD.gn** file in the same directory as **helloworld.c**.
```
touch BUILD.gn
vim BUILD.gn
```
The following is an example of **BUILD.gn**:
```
executable("hello_world") {
sources = [
"src/helloworld.c"
]
include_dirs = [
"include"
]
}
```
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
> - **executable** is a built-in template of gn. You can run the **gn help executable** command to view how to use this template.
>
> - **sources** represents the source code path, and **include_dirs** represents the header file path.
### Executing the Build Script
Run the following command to start the build:
```
hpm build
```
After all build operations are complete, the message "build succeed" is displayed. You need to check the build result.
![zh-cn_image_0000001262166533](figures/zh-cn_image_0000001262166533.png)
### Building an Image
Run the following command in the root directory of the current distribution:
```
hpm dist
```
The hpm-cli tool automatically starts the build. After the build is complete, an image file will be generated, as shown below:
```
out
|-xxdist.img
|-xx.file
```
## Publishing an HPM Part
To publish an HPM Part, you must obtain an account and create an organization (or join an existing organization). For details, see the online help on [DevEco Marketplace](https://repo.harmonyos.com).
After that, generate a public key on the local PC based on your invitation code (which can be obtained on the **My profile** page on [DevEco Marketplace](https://repo.harmonyos.com)), and configure the public key on the **My profile** page.
```
hpm config set loginUser {your-invitation-code}
hpm gen-keys
```
The generated file will be stored in **~\Users\yourname\.hpm\key**. Copy the content in the public key file **publicKey_your-account.pem** to the SSH public key on your **My profile** page.
Now you have the permission to publish HPM Parts in your organization.
In the directory where the HPM Part is located, run the following command to pack and publish the HPM Part:
```
hpm publish
```
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
> - To avoid HPM Part name conflicts, name an HPM Part in the format of **\@org_name/bundle_name**.
>
> - Your account must also be a member of **org_name** so that you can publish or update HPM Parts in the organization.
>
> - The published HPM Parts take effect only after security and content reviews.
## Using an HPM Part
### Using a Part
When developing a project, you usually need to reference other HPM Parts to accelerate development of specific functions. Installing dependencies could be a good way.
Visit [DevEco Marketplace](https://repo.harmonyos.com), search for HPM Parts that meet your service requirements by keywords, and then introduce them to your project. The typical operation procedure is as follows:
1. Run the **hpm init** command to create a bundle description file named **bundle.json**, which contains dependencies and other metadata such as the name and version.
2. Run the **hpm install <name>** command to install the dependency. The dependency will be written into the **dependencies** field in **bundle.json**.
3. Reference the header file in the code to implement the function.
4. Run the **hpm build** command to perform build and output the build result.
Run the following command in your project. Make sure that the project directory contains the **bundle.json** file.
```
$ hpm install @scope/the_bundle
```
The referenced HPM Part will be installed under **ohos_bundle** in the directory where your project is located. The directory structure is as follows:
```
project
├── ohos_bundle
│ └── scope
│ └─ the_bundle # <--- Referenced HPM Part
└── src
│ └─ main.c
├── bundle.json # Metadata declaration file
└── LICENSE
└── Makefile
└── README.md
```
Open the **bundle.json** file. You will see that the HPM Part has been introduced to the dependencies of your project.
```
{
"dependencies": {
"@scope/the_bundle": "^1.0.0"
}
}
```
You can edit the dependencies of multiple HPM Parts in this file.
```
{
"dependencies": {
"@scope/the_bundle1": "^1.0.0",
"@scope/the_bundle2": "^2.0.0",
"@scope/the_bundle3": "^3.0.0",
"@scope/the_bundle4": "^1.1.0"
}
}
```
Run the **hpm install** command again to download and install all HPM Parts that have not been installed.
### Installing Global HPM Parts
If the referenced HPM Part is shared by multiple projects, for example, the compiler toolchain, you can install it globally.
Run the following command in your project. Make sure that the project directory contains the **bundle.json** file.
```
$ hpm install -g @scope/the_tool
```
The referenced HPM Part will be installed in the directory specified by the **globalRepo** parameter of the **hpm config** command.
```
~\.hpm\global\ohos_bundles
│ └── scope
│ └─ the_tool # <--- Referenced HPM Part
```
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
> - For an HPM Part installed in a project, you can reference it using the environment variable **DEP_SCOPE_bundle_name** when running the hpm build command.
> For example, after you run **hpm i \@opensource/gn** to install an HPM Part, edit the build script in the **bundle.json** file as follows:
>
> ```
> "scripts": {
> "build": "${DEP_OPENSOURCE_gn}/gn --version"
> },
> ```
>
> Then, you can run the **hpm build** command to call gn functions.
>
> - For a globally installed HPM Part, you can directly call the HPM Part using an environment variable or reference the HPM Part using the **${key}/tool_name** parameter in the **hpm config set key value** command. Example:
>
> ```
> hpm i -g @ohos/opensource/gn
> hpm config BUILD_SYS_GN ~/.hpm/global/ohos_bundles/opensource/gn
> ```
>
> You can edit the build script in the **bundle.json** file as follows:
>
> ```
> "scripts": {
> "build": "${BUILD_SYS_GN}/gn --version"
> },
> ```
>
> Then, you can run the **hpm build** command to call gn functions.
en/device-dev/bundles/hpm-part-reference.md 0 → 100644
浏览文件 @ 2b8d818c
# HPM Part Reference
This section describes the HPM Part division rules, HPM Part types, HPM Part composition, metadata fields, and common CLI commands.
### HPM Part Division Rules
In principle, HPM Parts should be grouped at a fine-grained granularity to achieve maximum reuse. The following factors are taken into account:
- Independence: HPM Parts provide relatively independent features and can be independently built. Each HPM Part is capable of providing its own APIs and services for external systems.
- Coupling: If an HPM Part must depend on another one to provide services, they can be coupled to one HPM Part.
- Correlation: If a group of HPM Parts jointly implement a feature, and if other HPM Parts never depend on them, the group of HPM Parts can be combined into one HPM Part.
### HPM Part Type
HPM Parts are introduced for reuse purposes.
**Table 1** HPM Part types
| Item| Description|
| -------- | -------- |
| source | Distributed in the form of source code. It is depended by the target project, and can be compiled independently.|
| binary | Distributed in binary mode. It does not contain source code, such as build tools.|
| code-segment | Distributed in the form of code snippets and cannot be compiled independently. After the installation, it is restored to the specified directory and participates in other code build in the target project.|
| distribution | Distributed as a distribution and dependent on other HPM Parts. It does not contain source code (except build scripts). The build output is system images.|
| template | Distributed as a template and used by the **hpm init** command to create a template.|
| plugin | Distributed as a plugin of hpm-cli to provide more functions.|
### HPM Part Composition
An HPM Part contains the following:
- **src** directory for storing code files or code library of the HPM Part.
- **ohos_bundles** folder for storing dependent HPM Parts. The folder is automatically generated during HPM Part installation and does not need to be committed to the code library.
- **README.md** file for describing the HPM Part.
- **bundle.json** file for declaring metadata of the HPM Part.
- LICENSE file for open-source code.
```
my-bundle
|_ohos_bundles
|_headers
|_src
|_bundle.json
|_README.md
|_LICENSE
```
### src Source Code
HPM Part code files are the same as those in a common code directory. The only difference lies in the open APIs (declared in header files) provided by HPM Parts, which will be referenced by other HPM Parts and must be declared in **dirs** of **bundle.json**.
### README File
To help consumers find your HPM Part on [DevEco Marketplace](https://repo.harmonyos.com) and use it more conveniently, include a **README.md** file in the root directory of the HPM Part.
**README.md** is a file written using the markdown syntax.
The **README.md** file may include instructions on how to install, configure, and use the sample code in the HPM Part, as well as any other information helpful to the consumers.
The Readme file will be displayed on the homepage of the HPM Part on [DevEco Marketplace](https://repo.harmonyos.com).
## bundle.json File
The **bundle.json** file describes the metadata of an HPM Part. Each HPM Part has its own **bundle.json** file. The file content is as follows:
```
{
"name": "@myorg/demo-bundle",
"version": "1.0.0",
"license": "MIT",
"description": "bundle description",
"keywords": ["hos"],
"tags": ["applications", "drivers"],
"author": {"name":"","email":"","url":""},
"contributors":[{"name":"","email":"","url":""},{"name":"","email":"","url":""}],
"homepage": "http://www.foo.bar.com",
"repository": "https://git@gitee.com:foo/bar.git",
"private": false,
"publishAs": "code-segment",
"segment":{
"destPath":"/the/dest/path"
},
"dirs": {
"src": ["src/**/*.c"],
"headers": ["headers/**/*.h"],
"bin": ["bin/**/*.o"]
},
"scripts": {
"build": "make"
},
"envs": {},
"ohos": {
"os": "2.0.0",
"board": "hi3516",
"kernel": "liteos-a"
},
"rom": "10240",
"ram": "1024",
"dependencies": {
"@myorg/net":"1.0.0"
}
}
```
Each **bundle.json** file has the following fields:
- **name**: an HPM Part name, which starts with the at sign (@) and is separated with the organization name by the slash (/), for example, **\@myorg/mybundle**.
- **version**: version of the HPM Part, for example, 1.0.0. The version must comply with the Semantic Versioning Specification (SemVer) standards.
- **description**: a brief description of the HPM Part.
- **dependencies**: dependent HPM Parts.
- **envs**: parameters required for building the HPM Part, including global parameters and dependency parameters.
- **scripts**: commands executable to the HPM Part, such as commands for compiling, building, testing, and burning.
- **publishAs**: HPM Part publishing type, which can be **source**, **binary**, **distribution**, or **code-segment**.
- **segment**: destination path of the code-segment HPM Part, that is, the destination path of the files contained in the HPM Part after the HPM Part is installed.
- **dirs**: directory structure (such as the header file) generated for publishing.
- **ram** and **rom**: statistical information about the estimated read-only memory (ROM) and random access memory (RAM) usage.
- **ohos**: mappings among OpenHarmony versions, development boards, and kernels, separated by commas (,).
- Extended information: author, home page, code repository, license, tags, and keywords.
- For a distribution-level HPM Part, you can define the inheritance relationship and use the **base** field to describe the basic distribution and version that are inherited from.
- **private**: indicates whether an HPM Part is private. A private HPM Part cannot be found by other organizations. The default value is **false**.
## HPM CLI Commands
You can use the hpm-cli tool to manage the lifecycle of an HPM Part. The following table describes available hpm-cli commands. You can run the **hpm -h** command to get the command details.
**Table 2** Commands available on hpm-cli
| Command Type| Command Line| Description|
| -------- | -------- | -------- |
| Querying version information| **hpm -V** or **hpm --version**| Displays the version of the hpm-cli tool.|
| Querying help information| **hpm -h** or **hpm --version**| Displays the command list and help information.|
| hpm&nbsp;-h | Displays command help information.|
| Creating a project| hpm&nbsp;init&nbsp;bundle | Creates an HPM Part project.|
| hpm&nbsp;init&nbsp;-t&nbsp;template | Creates a scaffolding project from a template.|
| Installing HPM Parts| **hpm install** or **hpm i**| Installs dependent HPM Parts in the bundle.json file.|
| hpm&nbsp;install&nbsp;bundle\@version | Installs HPM Parts of a specified version.|
| Uninstalling HPM Parts| hpm&nbsp;uninstall&nbsp;bundle | Uninstalls dependent HPM Parts.|
| **hpm remove** or **hpm rm bundlename**| Uninstalls dependent HPM Parts.|
| Viewing information| **hpm list** or **hpm ls**| Displays the dependency tree of the HPM part.|
| hpm&nbsp;dependencies | Generates the dependency relationship data of the HPM Part. (This command is also integrated in the **hpm ui** command. After you run the hpm ui command, a hpm UI is displayed with the dependencies.)|
| Searching for HPM Parts| hpm&nbsp;search&nbsp;name | Searches for HPM Parts. **--json** is used to specify the search result in JSON format, and **-type** is used to set the target type, which can be **part**, **distribution**, or **code-segment**.|
| Setting HPM configuration items| hpm&nbsp;config&nbsp;set&nbsp;key&nbsp;value | Sets configuration items, such as the server address and network proxy.|
| hpm&nbsp;config&nbsp;delete&nbsp;key | Deletes configurations.|
| Updating HPM Part versions| hpm&nbsp;update | Updates the versions of dependent HPM Parts.|
| hpm&nbsp;check-update | Checks whether version updates are available to dependent HPM Parts.|
| Building| hpm&nbsp;build | Builds an HPM Part.|
| hpm&nbsp;dist | Builds a distribution. The build depends on the **dist** script in **scripts** of **bundle.json**.|
| Packing | hpm&nbsp;pack | Packs dependencies of local HPM Parts.|
| Burning| hpm&nbsp;run&nbsp;flash | Burns the firmware. The firmware burning depends on the **flash** script in **scripts** of **bundle.json**.|
| Publishing| hpm&nbsp;publish | Publishes an HPM Part, which must be unique in the repository and has a unique version. (An account is required for login.)|
| Running of extended commands| hpm&nbsp;run | Runs the commands in **scripts** defined in **bundle.json**. Multiple commands can be executed at a time by using **&&**.|
| Decompressing| hpm&nbsp;extract | Decompresses files in zip, tar, tgz, or .tar.gz format.|
| Starting UI| hpm&nbsp;ui | Starts the hpm UI locally. You can use the **-p** parameter to specify a port. On the Windows platform, the default browser is used to open the HPM UI.|
| Changing language| hpm&nbsp;lang | Alternates between Chinese and English on the CLI and UI.|
| Converting to HPM format| hpm&nbsp;x2h | Converts a Maven or npm package to an HPM Part and publishes it on the HPM platform.|
| Code segment restoration or cleanup| hpm&nbsp;code&nbsp;clean\|restore | Clears or restores the dependent code segment, which is equivalent to copying or deleting the code segment based on **segment.destPath**.|
| Generating a key| hpm&nbsp;gen-keys | Generates a public-private key pair and configures the public key on [DevEco Marketplace](https://repo.harmonyos.com), which enables password-free hpm-cli login for HPM Part publishing.|
| Generation of the third-party open source notice| hpm&nbsp;gen-notice | Generates a file providing the notice on third-party open source by combining the description of each HPM Part.|
## About Dependency
HPM Part dependencies are classified as mandatory and optional dependencies.
- Mandatory dependency: If HPM Part A must depend on HPM Part B to implement a feature (the APIs or services specific to HPM Part B must be called), HPM Part B is a mandatory dependency of HPM Part A.
- Optional dependency: If either HPM Part C or D is required for HPM Part A to implement a feature, and if HPM Parts C and D are interchangeable, HPM Parts C and D are optional dependencies of HPM Part A.
```
"dependencies": {
"@myorg/core":"1.0.0",
"?@myorg/plugin1":"1.0.0",
"?@myorg/plugin2":"1.1.0"
}
```
HPM Part dependencies can also be classified as compilation and development dependencies.
- Compilation dependency: dependency required for runtime.
- Development dependency: dependency required in non-runtime scenarios, such as static check, build, packing, test, and formatting tools.
```
"dependencies": {
"@myorg/core":"1.0.0"
},
"devDependencies": {
"@myorg/tool":"1.0.0"
}
```
Tags can be defined to group dependent HPM Parts. You can obtain the path of a group of dependent HPM Parts based on their tag. A tag starts with a number sign (#) and is defined as follows:
```
{
"dependencies": {
"#tool": {
"first_bundle": "1.0.0",
"second_bundle": "1.0.0"
},
"#drivers": {
"xx_bundle": "1.0.0",
"yy_bundle": "1.0.0"
}
}
}
```
HPM Part dependencies (including indirect dependencies) can be displayed by running the **hpm list** command or on the hpm UI, which is started by running the **hpm ui** command.
```
$ hpm list
+--demo@1.0.0
| +--@huawei/media@1.0.2
| +--@demo/sport_hi3518ev300_liteos_a@1.0.0
| | +--@demo/app@4.0.1
| | | +--@demo/build@4.0.1
| | | +--@demo/arm_harmonyeabi_gcc@4.0.0
| | +--@demo/liteos_a@4.0.0
| | | +--@demo/third_party_fatfs@4.0.0
| | | +--@demo/arm_harmonyeabi_gcc@4.0.0
| | +--@demo/init@4.0.0
| | +--@demo/dist_tools@4.0.0
```
## About Environment Variables
During HPM Part building, system-provided environment variables are required to define the output and link the required binary files.
These variables are injected into the context for executing scripts based on service requirements.
Therefore, their values can be directly obtained from the scripts. The following environment variables are available:
**Built-in environment variables**
- **DEP_OHOS_BUNDLES**: path of the **ohos_bundles** folder
- **DEP_BUNDLE_BASE**: path of the outermost HPM Part
**Global environment variables**
Global environment variables are defined by the **envs** attribute in **bundle.json**. You can obtain the values of global environment variables from all independent HPM Parts.
```
{
"envs": {
"compileEnv": "arm"
}
}
```
Different parameters can be passed to HPM Parts when introducing dependencies so that the compilation of dependent HPM Parts can meet the requirements of the current HPM Part. The parameters defined in the dependencies can be obtained from the context for executing the corresponding scripts.
```
{
"dependencies": {
"my-bundle": {
"version": "1.0.0",
"mode": "debug"
}
}
}
```
When linking to a binary file, the HPM Part needs to know the file path regarding the dependencies. Therefore, you need to pass the path as an environment variable to the HPM Part for building.
The passed environment variable is in **DEP\_BundleName** format, where **BundleName** indicates the name of the dependent HPM Part, for example, **DEP\_first\_bundle**.
## About Naming and Version Number
1. The name must be lowercase letters or digits and can be separated by underscores (\_), for example, **bundle**, **my\_bundle**, and **json2**.
2. Name of an HPM Part published to [DevEco Marketplace](https://repo.harmonyos.com) must start with the at sign (@) and is separated with the organization name by a slash (/), for example, **@my_org/part_name**.
3. The organization name and part name must be unique and distinguishably different with other names.
4. Names should be easy to understand.
5. An HPM Part version must be in the format of ***majorVersion***.***minorVersion***.***revisionVersion*** or ***majorVersion***.***minorVersion***.***revisionVersion***-***pre-releaseVersion***, for example, **1.0.0** and **1.0.0-beta**. For details, see [https://semver.org](https://semver.org/).
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或