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

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 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.

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

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
|+--@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

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 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.

你可能感兴趣的鸿蒙文章

harmony 鸿蒙HPM Part

harmony 鸿蒙HPM Part Overview

harmony 鸿蒙HPM Part Development