README_zh.md
1# Native软件打hnp包功能开发指导
2
3## 场景介绍
4
5Native包管理功能模块提供了对Native软件的打包、安装、卸载及运行管控的能力，当前文档主要对打包功能进行描述。
6
7## 接口说明
8
9 打包功能通过hnpcli命令行执行，不涉及对外接口。
10
11
12## 开发步骤
13
14**1. 操作前准备：Native软件包**
15
16 编译后的Native软件包里通常包含以下内容：
17 ```
18 bin #可执行二进制存放路径
19 cfg #配置文件存放路径
20 lib #依赖库存放路径
21 hnp.json #hnp配置文件
22 ... #其它
23 ```
24 其中hnp.json为hnp打包配置文件，需要放在软件包的外层目录，只能命名为hnp.json，内容要满足json文件的格式要求，该文件支持对可执行二进制进行软链接配置，具体的配置格式如下：
25 ```
26 {
27 "type":"hnp-config", #固定标识符“hnp-config”
28 "name":"xxx", #Native软件名
29 "version":"1.1", #版本号
30 "install":{
31 "links":[ #软链接配置信息
32 {
33 "source":"xxxxxx",
34 "target":"xxxxxx"
35 }
36 ]
37 }
38 }
39 ```
40 注：
41 1. 用户在配置文件中指定了软链接关系则安装时根据用户配置进行软链接设置。如果用户不使用配置文件或者配置文件中没有设置软链接，则安装时默认将软件包内bin目录下的可执行二进制都进行软链接。
42 2. 为了保证bin目录里面的二进制执行过程中能自动加载lib下的库文件，则需要在编译二进制时增加以下rpath链接选项，指明库文件和二进制的相对位置关系（${ORIGIN}为当前二进制位置）。
43
44 ```
45 ldflags = [
46 "-Wl,-rpath=${ORIGIN}/../lib",
47 "-Wl,--disable-new-dtags",
48 ]
49 ```
50 3. Native软件包名和版本号不支持空格和特殊字符，Native软件包中文件目录不支持中文目录。
51 4. 打包文件路径长度不超过4096个字符，打包文件个数不超过65535，打包后hnp文件大小不超过4GB。
52 5. hnp安装之后，用户通常以others权限运行。在windows上打包hnp包，安装后文件默认赋予others可执行权限。在linux、mac、ohos操作系统上打包hnp包，安装后文件继承打hnp包前文件在操作系统上的UGO权限。
53
54 样例：
55 ```
56 hnpsample软件包目录：
57
58 hnpsample
59 |__bin
60 |__hnpsample
61 |__cfg
62 |__hnpsample.cfg
63 |__lib
64 |__libhnpsamplelib.z.so
65 |__hnp.json
66
67 配置文件hnp.json内容如下：
68 {
69 "type":"hnp-config",
70 "name":"hnpsample",
71 "version":"1.1",
72 "install":{
73 "links":[
74 {
75 "source":"/bin/hnpsample",
76 "target":"hnpsample"
77 }
78 ]
79 }
80 }
81 注：
82 上述软链接关系表示为：作为target的hnpsample文件是生成的软链接文件，它是由源文件/bin/hnpsample软链接生成的。
83 ```
84**2. Native软件包打包**
85
86 Native软件打包的目的是为了将Native软件打包成hnp文件以便后面上传到应用市场，为支持不同操作系统（linux、windows、mac、ohos），当前已在OpenHarmony sdk中提供了hnpcli工具，用户通过hnpcli命令进行打包。
87
88 hnpcli命令提供帮助信息：
89 ```
90 帮助命令：hnpcli -h 或者 hnpcli help
91 输出内容：
92 usage:hnpcli <command> <args> [-i <software package dir>][-o <hnp output path>][-n <native package name>][-v <native package version>]
93
94 These are common hnpcli commands used in various situations:
95
96 pack: packet native software package to .hnp file
97 hnpcli pack <-i [source path]> <-o [dst path]> <-n [software name]> <-v [software version]>
98 -i : [required] input path of software package dir
99 -o : [optional] output path of hnp file. if not set then ouput to current directory
100 -n : [optional] software name. if not hnp.json in input dir then must set
101 -v : [optional] software version. if not hnp.json in input dir then must set
102
103 for example:
104
105 hnpcli pack -i /usr1/native_sample -o /usr1/output -n native_sample -v 1.1
106 ```
107 hnpcli打包命令有两种使用方式。
108
109 一种是软件包里有hnp.json的打包命令：
110 ```
111 hnpcli pack -i [待打包路径] < -o [输出路径] >
112 注：
113 1. 如果没有指定-o，则输出路径为当前目录。
114 2. 打包路径下有hnp.json配置文件，使用配置文件名里的软件名和版本号作为打包参数。
115 ```
116 另一种是软件包里没有hnp.json的打包方式：
117 ```
118 hnpcli pack -i [待打包路径] < -o [输出路径] > -n [软件名] -v [版本号]
119 注：
120 1. 打包路径下没有hnp.json配置文件，则需要用户传入-n和-v参数，否则打包失败（打包软件会根据入参在压缩文件根目录中主动生成hnp.json）。
121 ```
122 打包成功后会在输出路径下生成"[Native软件名].hnp"的文件。
123
124 样例：
125 ```
126 1. 对hnpsample软件进行打包，由于hnpsample目录下存在hnp.json文件，不需要指定软件名和版本号。因此命令如下：
127 hnpcli pack -i ./hnpsample -o ./out
128 2. 命令返回成功，则在out目录下生成hnpsample.hnp文件
129 ```
130