harmony 鸿蒙HPM Part Reference

  • 2022-08-09
  • 浏览 (740)

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

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 -h Displays command help information.
Creating a project hpm init bundle Creates an HPM Part project.
hpm init -t 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 install bundle\@version Installs HPM Parts of a specified version.
Uninstalling HPM Parts hpm uninstall 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 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 search 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 config set key value Sets configuration items, such as the server address and network proxy.
hpm config delete key Deletes configurations.
Updating HPM Part versions hpm update Updates the versions of dependent HPM Parts.
hpm check-update Checks whether version updates are available to dependent HPM Parts.
Building hpm build Builds an HPM Part.
hpm dist Builds a distribution. The build depends on the dist script in scripts of bundle.json.
Packing hpm pack Packs dependencies of local HPM Parts.
Burning hpm run flash Burns the firmware. The firmware burning depends on the flash script in scripts of bundle.json.
Publishing hpm 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 run Runs the commands in scripts defined in bundle.json. Multiple commands can be executed at a time by using &&.
Decompressing hpm extract Decompresses files in zip, tar, tgz, or .tar.gz format.
Starting UI hpm 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 lang Alternates between Chinese and English on the CLI and UI.
Converting to HPM format hpm x2h Converts a Maven or npm package to an HPM Part and publishes it on the HPM platform.
Code segment restoration or cleanup hpm code 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 gen-keys Generates a public-private key pair and configures the public key on DevEco Marketplace, which enables password-free hpm-cli login for HPM Part publishing.
Generation of the third-party open source notice hpm 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
|+--@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

0  赞