1# HPM Part开发指导 2 3 4## HPM Part开发指导概述 5 6通常情况下，[DevEco Marketplace](https://repo.harmonyos.com)中能找到您开发常用的资源，可以通过依赖将所需的资源引入工程中。若现有的资源不能完全满足，可以自己开发并将其以HPM Part的格式发布。安装好hpm-cli工具后，就可以进行Part的开发了。 7 8>  **说明：** 9> 下述操作建议在Ubuntu 18.04及以上版本运行。 10 11 12## 安装HPM命令行工具 13 14在进行HPM Part开发之前，首先需要安装包管理器命令行工具hpm-cli。Hpm-cli是一个基于Node.js开发的跨平台的命令行工具，而要运行hpm命令，需要先安装Node.js，然后使用npm来安装hpm。 15 16 17### 安装Node.js及hpm-cli 18 191. 安装Node.js。 20 从官网下载并在本地安装Node.js. 21 22 推荐安装[Node.js](https://nodejs.org/)最新的LTS版本 (不低于12.x)。 23 242. 通过Node.js自带的npm安装hpm-cli命令行工具。执行以下命令： 25 26 ``` 27 npm install -g @ohos/hpm-cli 28 ``` 29 303. 安装完成后执行如下命令，显示hpm版本，即安装成功。 31 32 ``` 33 hpm -V 或 hpm --version 34 ``` 35 364. （可选）如果需要升级hpm版本，请执行如下命令： 37 38 ``` 39 npm update -g @ohos/hpm-cli 40 ``` 41 42 43### 配置hpm-cli（可选） 44 45安装完hpm命令行工具后，如果需要更改配置信息（如代理，shell路径），可执行以下命令可以查看hpm配置： 46 47 48``` 49hpm config 50``` 51 52 上述命令执行后将会显示hpm的默认配置，您可以根据自己需要对默认配置进行修改，以下是hpm的常用配置： 53 54``` 55registry = https://hpm.harmonyos.com 56### login Settings 57# loginUser = invitation_code 58 59#### Path Settings 60shellPath = C:\WINDOWS\System32\cmd.exe 61# shellPath = C:\Program Files\Git\bin\sh.exe 62# globalRepo = C:\Users\username\.hpm\global 63 64#### Network Settings 65# no_proxy = *.server.com 66# http_proxy = http://user:pwd@proxy_server:port 67# https_proxy = http://user:pwd@proxy_server:port 68# strictSsl = true 69 70#### Other Settings 71# privateSupport = true|false 72# ignoreBundles = @ohos/llvm,@ohos/gn, 73# OSPlatform = Auto|linux|darwin|win32 74``` 75 76 77## 创建HPM Part 78 79创建HPM Part有以下两种方式，开发者可根据自己的需要选择使用。 80 81 82### 使用模板创建HPM Part 83 841. 请执行如下命令创建目录： 85 86 ``` 87 hpm init -t default mybundle 88 ``` 89 90 >  **说明：** 91 > -t后的default表示使用名为'default'模板创建（也可以换作其他的模板，如simple、dist等） 92 93 生成目录结构如下： 94 95 ``` 96 / 97 ├── headers # 头文件（样例） 98 │ └── main.h 99 └── src # 源代码（样例） 100 │ └─ main.c 101 ├── bundle.json # 元数据声明文件 102 └── LICENSE # 许可协议文本 103 └── Makefile # 编译描述文件（样例） 104 └── README.md # Part的自述文件 105 106 ``` 107 1082. 接下来根据需要，实现Part内部的功能代码，以及编译脚本。 109 110 ``` 111 hpm init -t {templatename} -d {dir} {name} 112 ``` 113 114 >  **说明：** 115 > - -t {templatename} ：指的是模板名称。 116 > 117 > - -d {dir}：是要创建的Part所存放的路径。 118 > 119 > - name：为要创建的Part名称。 120 121hpm-cli除了提供了少量默认模板之外，其他模板均存储在[DevEco Marketplace](https://repo.harmonyos.com)，可以使用命令hpm search -t template从[DevEco Marketplace](https://repo.harmonyos.com)搜索模板。 122 123 124 125 126### 将现有工程定义为Part 127 128如果您已经有了代码工程，需要分发的hpm平台，只需要在当前工程目录下（例如mybundle2），执行如下命令，系统会引导您输入组件名称和版本等信息。 129 130 131``` 132hpm init 133``` 134 1351. 输入名称后回车（如mybundle2）。 136 1372. 接下来依次输入版本、描述等信息后，会在当前目录下会生成一个bundle.json文件。 138 1393. 也可以打开bundle.json文件。 140 141 ``` 142 $ hpm init 143 Your bundle will be created in directory ~\demo\mybundle2 144 ? bundle name mybundle2 145 ? version 1.0.0 146 ... 147 Initialization finished. 148 ``` 149 1504. 打开bundle.json文件修改其他信息（如作者、代码仓库、代码目录、命令脚本、依赖组件等），如下（仅示意）： 151 152 ``` 153 { 154 "name": "mybundle2", 155 "version": "1.0.0", 156 "publishAs": "code-segment", 157 "dirs":{ 158 ".":["README.md"], 159 "src":["test.c"], 160 "header":["header/test.h" ], 161 "src/common":["src/common/foobar.txt"] 162 }, 163 "scripts": { 164 "build": "make -${args}" 165 }, 166 "dependencies": { 167 "@ohos/cjson": "^1.0.0", 168 "@ohos/foobar": "^1.2.0" 169 } 170 } 171 ``` 172 173 174## 定义发行版 175 176发行版的元数据文件中定义了其依赖的Parts，以及如何编译、链接这些Parts，生成镜像文件的编译脚本。 177 178下方以bundle.json中定义为示例，以下示例的编译命令dist，采用hb编译框架描述。 179 180 181``` 182{ 183 "name": "@your/dist_name", 184 "version": "2.2.0", 185 "publishAs": "distribution", 186 "description": "describe it", 187 "scripts": { 188 "config_hb": "hb set -root $DEP_BUNDLE_BASE", 189 "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" 190 }, 191 "envs": { 192 "debug": false 193 }, 194 "dirs": { 195 "scripts": "scripts/*" 196 }, 197 "dependencies": { 198 "@ohos/build_lite": "2.2.0", 199 "@ohos/gn": "1.1.1", 200 "@ohos/llvm": "1.1.1", 201 "@ohos/hc_gen": "1.1.0", 202 "@ohos/ninja": "1.1.0", 203 ...... 204 }, 205 "ohos": { 206 "os": "2.2-Beta", 207 "board": "hi3516", 208 "kernel": "liteos-a" 209 }, 210 "keywords": ["hispark", "hi3516"], 211 "repository": "https://gitee.com/openharmony/your-project", 212 "license": "Apache V2" 213} 214``` 215 216 217## 编译构建 218 219完成代码开发后，如果Part的代码是可以独立编译的，可以配置编译工具和脚本以完成二进制的生成。 220 221hpm-cli具备命令集成的能力，开发者可以选择任意的适合项目所采用的语言编译工具（如make，gcc，gn等）。只需在当前项目的bundle.json文件中定义scripts脚本中的build命令，就可以通过执行hpm build执行编译。 222 223 224### 定义编译脚本 225 226以编译一个app目录下helloworld可执行文件为例： 227 228 229``` 230app 231├── BUILD.gn 232├── include 233│ └── helloworld.h 234└── src 235 └── helloworld.c 236``` 237 238在helloworld.c同级目录下新建一个BUILD.gn 239 240 241``` 242touch BUILD.gn 243vim BUILD.gn 244``` 245 246以下是BUILD.gn的样例，仅供参考 247 248 249``` 250executable("hello_world") { 251 sources = [ 252 "src/helloworld.c" 253 ] 254 255 include_dirs = [ 256 "include" 257 ] 258} 259``` 260 261>  **说明：** 262> - “executable”是gn内置模板，可以用“gn help executable ”查看使用方法。 263> 264> - “sources ”是源码路径，“include_dirs ”是头文件路径。 265 266 267### 执行编译 268 269在当前文件夹下，执行编译命令： 270 271 272``` 273hpm build 274``` 275 276在完成一系列的编译动作后，显示build succeed。检查编译的输出结果： 277 278 279 280 281### 编译image 282 283在当前发行版根目录下，执行如下命令。 284 285 286``` 287hpm dist 288``` 289 290hpm-cli工具会自动执行编译，生成镜像文件，如： 291 292 293``` 294out 295|-xxdist.img 296|-xx.file 297``` 298 299 300## 发布上架 301 302要发布Part到hpm，你需要先具备账号，并创建组织，创建组织的条件及详细步骤请参考[DevEco Marketplace](https://repo.harmonyos.com)上的帮助说明。 303 304完成账号申请和组织创建（或者加入一个现有的组织）后，您需要根据个人的邀请码（在[DevEco Marketplace](https://repo.harmonyos.com)的个人中心页查看），在本机生成公钥，并在[DevEco Marketplace](https://repo.harmonyos.com)的个人中心进行配置。 305 306 307``` 308hpm config set loginUser {your-invitation-code} 309hpm gen-keys 310``` 311 312生成的文件将会存放在~\Users\yourname\.hpm\key下，将公钥文件(publicKey_your-accout.pem)中内容拷贝到hpm个人中心的SSH公钥中。 313 314完成上述操作后，你就具备了在您的组织内发布Part的权限了。 315 316在Part所在目录，执行命令hpm publish，将会完成组件的打包发布操作。 317 318 319``` 320hpm publish 321``` 322 323>  **说明：** 324> - 为避免Part名称冲突，发布的Part的名称需限定在组织范围内，即命名为\@org_name/bundle_name的格式。 325> 326> - 你的账号也必须是org_name内的成员，才可以发布或更新组织内的Part。 327> 328> - 发布的组件，需要通过安全及内容审核，才能正式生效。 329 330 331## 使用HPM Part 332 333 334### 使用Part 335 336通常开发一个项目，需要引用其他的组件以加快特定功能的开发，可以采用安装依赖的方式。 337 338首先去[DevEco Marketplace](https://repo.harmonyos.com)，根据关键字去搜索满足您的需求的组件，找到合适的组件后，将其引入到您的工程。典型的操作步骤包括： 339 3401. 使用hpm init命令创建一个包描述文件（名为bundle.json，包含了依赖和一些其他的元数据，如名称、版本等）。 341 3422. 使用hpm install <name>命令安装依赖（依赖写入bundle.json的dependencies字段）。 343 3443. 代码中共引用头文件，实现功能。 345 3464. 使用hpm build命令执行编译，输出编译结果。 347 348 在您的Part工程中（工程目录中必须包含bundle.json文件）执行如下命令： 349 350``` 351$ hpm install @scope/the_bundle 352``` 353 354 引用的Part将会被安装到你的工程所在的目录的ohos_bundle下 355 356``` 357project 358├── ohos_bundle 359│ └── scope 360│ └─ the_bundle # <---引用的组件将会出现在这 361└── src 362│ └─ main.c 363├── bundle.json # 元数据声明文件 364└── LICENSE 365└── Makefile 366└── README.md 367``` 368 369打开bundle.json文件，可以看到Part已经被引入到您的工程的依赖中。 370 371 372``` 373{ 374 "dependencies": { 375 "@scope/the_bundle": "^1.0.0" 376 } 377} 378``` 379 380您也可以一次性在此文件中编辑多个Part的依赖 381 382 383``` 384{ 385 "dependencies": { 386 "@scope/the_bundle1": "^1.0.0", 387 "@scope/the_bundle2": "^2.0.0", 388 "@scope/the_bundle3": "^3.0.0", 389 "@scope/the_bundle4": "^1.1.0" 390 } 391} 392``` 393 394再执行hpm install命令，将会一次性将所有未安装的Part一次性全部下载并安装完成。 395 396 397### 安装全局Part 398 399如果引用的Part是多个项目共用的组件（如编译工具链），你可以全局安装 400 401 在您的Part工程中（工程目录中必须包含bundle.json文件）执行如下命令： 402 403``` 404$ hpm install -g @scope/the_tool 405``` 406 407 引用的Part将会被安装到你在hpm config中设置的globalRepo所指定的目录下： 408 409``` 410~\.hpm\global\ohos_bundles 411│ └── scope 412│ └─ the_tool # <---引用的组件将会出现在这 413``` 414 415>  **说明：** 416> - 在项目安装的Part，在执行hpm编译命令时可以通过引用环境变量DEP_SCOPE_bundle_name，例如： 417> 通过hpm i \@opensource/gn安装后，可以编辑bundle.json中的编译脚本，如下： 418> 419> ``` 420> "scripts": { 421> "build": "${DEP_OPENSOURCE_gn}/gn --version" 422> }, 423> ``` 424> 425> 然后就可以通过执行hpm build将调用gn的功能。 426> 427> - 在全局安装的Part，可以通过设置系统环境变量，直接调用，或者hpm config set key value的方式，通过${key}/tool_name的方式引用，例如： 428> 429> ``` 430> hpm i -g @ohos/opensource/gn 431> hpm config BUILD_SYS_GN ~/.hpm/global/ohos_bundles/opensource/gn 432> ``` 433> 434> 可以编辑bundle.json中的编译脚本，如下： 435> 436> ``` 437> "scripts": { 438> "build": "${BUILD_SYS_GN}/gn --version" 439> }, 440> ``` 441> 442> 然后就可以通过执行hpm build将调用gn的功能。 443
