一、简介

大量生产力软件需在设备上运行Native软件包（如Python、Node、Java等）。当前方案支持通过hnpcli工具将Native软件包打包为hnp（OpenHarmony Native Package）格式，再嵌入HAP包分发，最终实现Native软件包的安装、运行及命令行调用，满足开发者或自动化测试人员的使用需求。

二、Native软件包开发流程

所有Native软件包需通过以下三步集成到HAP应用中，以HAP形式分发使用：

1. 将Native软件包源文件打包为hnp包；
2. 将hnp包嵌入HAP包；
3. 对HAP包进行签名。

2.1 命令行工具开发流程

2.1.1 打包Native软件为hnp包

参考《Native软件打hnp包功能开发指导》，使用hnpcli工具完成打包。

2.1.2 将hnp包嵌入HAP包

操作步骤：

1. 下载DevEco Studio，创建HAP工程；
2. 在HAP工程根目录新建hnp文件夹，按设备ABI（如arm64-v8a）创建子目录，存放hnp包（支持子目录结构），示例如下：

   HAP工程根目录  
   └── hnp                  # hnp根目录  
       └── arm64-v8a       # 设备ABI目录  
           ├── python.hnp  # hnp包  
           └── sub_dir     # 子目录（可选）  
               └── test.hnp  
   

3. 配置module.json5文件：在module字段下添加hnpPackages，声明hnp包路径及类型（公有public/私有private），示例：

   "hnpPackages": [  
     {  
       "package": "python.hnp",       // ABI目录下的相对路径  
       "type": "public"               // 公有类型（所有应用可访问）  
     },  
     {  
       "package": "sub_dir/test.hnp",  
       "type": "private"              // 私有类型（仅当前HAP可访问）  
     }  
   ]  
   

4. 编译HAP包：点击DevEco Studio菜单栏Build > Build Hap(s)/APP(s) > Build Hap(s)；
5. 执行打包命令：参考《hap包模式打包指令》，使用--hnp-path指定hnp根目录，生成未签名HAP包。

核心规格说明：

• 安装路径：

  • 公有hnp包：/data/service/hnp/<name>_<version>（环境变量HNP_PUBLIC_HOME=/data/service/hnp）；
  • 私有hnp包：/data/app/<name>_<version>（环境变量HNP_PRIVATE_HOME=/data/app）。
  • 环境变量优先级：HNP_PRIVATE_HOME > HNP_PUBLIC_HOME（同名二进制优先执行私有路径）。

• 访问权限：

  • 公有包：所有应用可访问；私有包：仅嵌入它的HAP应用可访问。

• 卸载与冲突：

  • 卸载HAP时，其嵌入的所有hnp包会同步卸载（若二进制被其他应用占用，卸载失败）；
  • 同名公有包（hnp.json中name相同）不可重复安装，后安装的HAP需将其改为私有包或卸载前序HAP。

2.1.3 HAP包签名流程

操作步骤：

1. 配置签名信息：参考应用/服务签名的“手动签名”章节；
2. 下载签名工具：hap-sign-tool.jar；
3. 执行签名命令：参考应用包签名工具，使用步骤1的配置参数生成签名后的HAP包。

2.2 IDE工具开发流程

暂不支持，待后续开发。

三、Native软件包使用方法

3.1 在HAP应用中调用Native二进制

以C++为例，可通过system、execv等函数执行二进制。

• 公有hnp包二进制软链接路径：/data/service/hnp/bin（已加入环境变量）；
• 私有hnp包二进制软链接路径：/data/app/bin（已加入环境变量）。

3.2 通过hdc shell执行

操作步骤：

1. 安装含Native软件包的HAP应用（从应用市场下载）；
2. 连接设备并进入shell：hdc shell；
3. 定位安装路径并执行：
   • 公有hnp包物理路径：/data/app/el1/bundle/<bundle-id>/hnppublic；
   • 私有hnp包物理路径：/data/app/el1/bundle/<bundle-id>/hnp（userid默认100）。
     示例：cd /data/app/el1/bundle/com.example.demo/hnp/bin && ./python

附1：Native软件打hnp包功能开发指导

场景介绍

通过hnpcli工具将Native软件包打包为hnp格式，支持后续安装、运行管控。

开发步骤

1. 准备Native软件包

编译后的Native软件包需包含以下结构（示例）：

hnpsample/               # 软件包根目录  
├── bin/                 # 可执行二进制  
│   └── hnpsample  
├── cfg/                 # 配置文件  
│   └── hnpsample.cfg  
├── lib/                 # 依赖库  
│   └── libhnpsamplelib.z.so  
└── hnp.json             # 打包配置文件（必填）  

关键配置：hnp.json
用于声明软件信息及软链接规则，格式如下：

{  
  "type": "hnp-config",   // 固定值  
  "name": "hnpsample",    // 软件名（无空格/特殊字符）  
  "version": "1.1",       // 版本号（无空格/特殊字符）  
  "install": {  
    "links": [            // 软链接配置（可选）  
      {  
        "source": "/bin/hnpsample",  // 源文件路径（相对软件包根目录）  
        "target": "hnpsample"        // 软链接文件名（生成在bin目录）  
      }  
    ]  
  }  
}  

注意事项：

• 若未配置links，默认对bin目录下所有二进制创建软链接；
• 二进制需添加rpath链接选项，确保自动加载lib目录依赖：

  ldflags = [  
    "-Wl,-rpath=${ORIGIN}/../lib",  // 相对路径指向lib目录  
    "-Wl,--disable-new-dtags"  
  ]  
  

• 限制：
  • 软件名/版本号不支持空格、特殊字符；
  • 目录不支持中文；
  • 打包路径长度≤4096字符，文件数≤65535，hnp文件大小≤4GB；
  • 权限继承：Windows打包默认赋予others可执行权限；Linux/mac/OHOS打包继承原文件UGO权限。

2. 使用hnpcli打包

hnpcli工具已集成于OpenHarmony SDK，支持跨平台（Linux/Windows/mac/OHOS）。

命令格式：

# 查看帮助  
hnpcli -h  

# 打包（含hnp.json时）  
hnpcli pack -i <待打包目录> [-o <输出目录>]  

# 打包（不含hnp.json时，需手动指定名称和版本）  
hnpcli pack -i <待打包目录> [-o <输出目录>] -n <软件名> -v <版本号>  

示例：

# 对含hnp.json的hnpsample打包  
hnpcli pack -i ./hnpsample -o ./out  
# 输出：./out/hnpsample.hnp  

附2：hap包模式打包指令

示例命令

• Stage模型：

  java -jar app_packing_tool.jar \  
    --mode hap \  
    --json-path <module.json路径> \  
    --resources-path <资源路径> \  
    --ets-path <ets文件目录> \  
    --index-path <resources.index路径> \  
    --pack-info-path <pack.info路径> \  
    --out-path <输出路径/srcEntrance.hap> \  
    --force true \  
    --compress-level 5 \  
    --pkg-context-path <pkgContextInfo.json路径> \  
    --hnp-path <hnp根目录>  # 指定hnp包路径  
  

• FA模型：

  java -jar app_packing_tool.jar \  
    --mode hap \  
    --json-path <config.json路径> \  
    --maple-so-path <so文件路径> \  
    --profile-path <CAPABILITY.profile路径> \  
    --dex-path <dex文件路径> \  
    --resources-path <资源路径> \  
    --index-path <resources.index路径> \  
    --out-path <输出路径> \  
    --force true \  
    --compress-level 5 \  
    --hnp-path <hnp根目录>  # 指定hnp包路径  
  

参数说明

指令	是否必选	选项	描述	备注
–mode	是	hap	打包类型（固定为hap）	-
–json-path	是	-	配置文件路径（Stage模型为module.json，FA模型为config.json）	-
–out-path	是	-	输出HAP路径（文件名需以.hap结尾）	-
–hnp-path	否	-	hnp根目录路径（指定后将hnp包打入HAP）	-
–force	否	true/false	目标文件存在时是否强制覆盖（默认false）	-
–compress-level	否	1-9	压缩等级（1-9，默认1，需配合compressNativeLibs=true生效）	-
–resources-path	否	-	资源包路径	-
–index-path	否	-	resources.index文件路径	-
–ets-path	否	-	ets文件目录路径	仅Stage模型
–js-path	否	-	js文件目录路径	仅Stage模型
–dex-path	否	-	dex文件路径（支持多文件，用逗号分隔）	仅FA模型
–maple-so-path	否	-	so文件路径（支持多文件，用逗号分隔）	仅FA模型

参考资料

• OpenHarmony hnp功能说明
• HAP打包工具
• HAP签名工具