1# Developing Bundles<a name="EN-US_TOPIC_0000001051690861"></a> 2 3- [Creating a Bundle](#section717481119145) 4- [Defining an Existing Project as a Bundle](#section102861955201410) 5- [Releasing the Bundle on the HPM Platform](#section1318574233211) 6- [Referencing a Bundle](#section19311124115315) 7- [Installing a Bundle Globally](#section165131927192120) 8- [Compiling a Bundle](#section136732148541) 9- [Defining the Build Script](#section10274147111610) 10- [Executing the Build Script](#section879301916172) 11- [Defining a Distribution](#section413216495619) 12- [Defining Scripts](#section11503171219190) 13- [Building a Distribution](#section4694125521912) 14 15You can use any of the following methods to develop OpenHarmony bundles: 16 17- Create a new bundle from scratch. 18- Define an existing source code project as a bundle. 19 20## Creating a Bundle<a name="section717481119145"></a> 21 22Generally, you can find commonly used bundles on the [HPM](https://hpm.harmonyos.com/#/en/home) website. If they cannot meet your requirements, you can develop a bundle on your own. 23 24You can publish bundles in the HPM repository if you like, so that your peers have an option to use them. 25 26Assume that you are planning to create a new bundle **my-bundle** in **D:/source**. Run the **hpm init** command to create the scaffold code for this bundle. For example, you can go to **D:/source** and run the following command: 27 28``` 29hpm init -t default -d demo mybundle 30``` 31 32The **'default'** template will be used to create a bundle named **mybundle** in the **demo** directory in **D:/source**. 33 34``` 35demo 36├── headers # Header file (example) 37│ └── main.h 38└── src # Source code (example) 39│ └─ main.c 40├── bundle.json # Metadata declaration file 41└── LICENSE # License agreement 42└── Makefile # Compilation description file (example) 43└── README.md # Readme file 44 45``` 46 47Then, complete your coding based on service requirements and generate the build script. Finally, use **git** to commit your code \(including the **bundle.json** file\) to the code hosting repository, such as gitee. 48 49> **NOTE:** 50>``` 51>hpm init -t {templatename} -d {dir} {name} 52>``` 53>- **-t \{templatename\}** indicates the template name. 54>- **-d \{dir\}** indicates the path for storing the bundle to be created. 55>- **name** indicates the name of the bundle to be created. 56 57The hpm provides a few default templates. More templates are available on the HPM server. You can run the **hpm search -t template** command to search for a template stored on the server. 58 59 60 61## Defining an Existing Project as a Bundle<a name="section102861955201410"></a> 62 63If you have a code project and need to distribute it on the HPM platform, run the following command in the current project directory, for example, **mybundle2**: 64 65``` 66hpm init 67``` 68 691. Enter a bundle name \(**mybundle2** as an example\) and press **Enter**. 702. Enter the version and description. A **bundle.json** file will be generated in the current directory. 713. Open the** bundle.json** file as you like. 72 73 ``` 74 $ hpm init 75 Your bundle will be created in directory ~\demo\mybundle2 76 ? bundle name mybundel2 77 ? version 1.0.0 78 ... 79 Initialization finished. 80 ``` 81 82 831. Modify other information \(such as the author, code repository, code directory, command script, and dependent bundles\) in **bundle.json**. An example is shown below: 84 85 ``` 86 { 87 "name": "mybundle2", 88 "version": "1.0.0", 89 "publishAs": "code-segment", 90 "dirs":{ 91 ".":["README.md"], 92 "src":["test.c"], 93 "header":["header/test.h" ], 94 "src/common":["src/common/foobar.txt"] 95 }, 96 "scripts": { 97 "build": "make -${args}" 98 }, 99 "dependencies": { 100 "@ohos/cjson": "^1.0.0", 101 "@ohos/foobar": "^1.2.0" 102 } 103 } 104 ``` 105 106 107## Releasing the Bundle on the HPM Platform<a name="section1318574233211"></a> 108 109To release a bundle on the HPM platform, you need to obtain an account and create an organization \(or join an existing organization\). For details, see the online help on the [HPM](https://hpm.harmonyos.com/#/en/home) website. 110 111After that, generate a public key on the local PC based on your invitation code \(which can be obtained on the **My profile** page on the HPM website\), and configure the public key on the **My profile** page. 112 113``` 114hpm config set loginUser {your-invitation-code} 115hpm gen-keys 116``` 117 118The generated file will be stored in **\~\\Users\\yourname\\.hpm\\key**. Copy the content in the public key file **publicKey\_your-account.pem** to the SSH public key on your **My profile** page. 119 120After finishing the preceding operations, you then have the permission to release bundles in your organization. 121 122In the directory where the bundle is located, run the following command to package and release the bundle: 123 124``` 125hpm publish 126``` 127 128> **NOTE:** 129>- To avoid bundle name conflicts, name a released bundle in the format of **@org\_name/bundle\_name**. 130>- Your account must also be a member of **org\_name** so that you can release or update bundles in the organization. 131>- The released bundles take effect only after security and content reviews. 132 133## Referencing a Bundle<a name="section19311124115315"></a> 134 135Generally, when developing a project, you may need to reference other bundles in order to accelerate development of specific functions. Installing dependencies could be a good way. 136 137Go to the HPM website, search for bundles that meet your service requirements by keywords, and then introduce the bundles to your project. 138 139Run the following command in your bundle project. Make sure that the project directory contains the **bundle.json** file. 140 141``` 142$ hpm install @scope/the_bundle 143``` 144 145The referenced bundle will be installed under **ohos\_bundle** in the directory where your project is located. The directory structure is as follows: 146 147``` 148project 149├── ohos_bundle 150│ └── scope 151│ └─ the_bundle # <--- Referenced bundle 152└── src 153│ └─ main.c 154├── bundle.json # Metadata declaration file 155└── LICENSE 156└── Makefile 157└── README.md 158``` 159 160Open the **bundle.json** file. You will see that the bundle has been introduced to the dependencies of your project. 161 162``` 163{ 164"dependencies": { 165 "@scope/the_bundle": "^1.0.0" 166 } 167} 168``` 169 170You can also edit the dependencies of multiple bundles in this file at a time. 171 172``` 173{ 174"dependencies": { 175 "@scope/the_bundle1": "^1.0.0", 176 "@scope/the_bundle2": "^2.0.0", 177 "@scope/the_bundle3": "^3.0.0", 178 "@scope/the_bundle4": "^1.1.0" 179 } 180} 181``` 182 183Run the **hpm install** command again to download and install all bundles that have not been installed. 184 185## Installing a Bundle Globally<a name="section165131927192120"></a> 186 187If the referenced bundle is one shared by multiple projects, for example, the compiler toolchain, you can install it globally. 188 189Run the following command in your bundle project. Make sure that the project directory contains the **bundle.json** file. 190 191``` 192$ hpm install -g @scope/the_tool 193``` 194 195The referenced bundle will be installed in the directory specified by the **globalRepo** parameter of the **hpm config** command. 196 197``` 198~\.hpm\global 199│ └── scope 200│ └─ the_tool # <--- Referenced bundle 201``` 202 203> **NOTE:** 204>- For a bundle installed in a project, you can reference it using the environment variable **DEP\_SCOPE\_bundle\_name** when running the hpm compilation command. 205>For example, after you run **hpm i @opensource/gn** to install a bundle, you can edit the build script in the **bundle.json** file as follows: 206>``` 207>"scripts": { 208> "build": "${DEP_OPENSOURCE_gn}/gn --version" 209> }, 210>``` 211>Then, you can run the **hpm build** command to call GN functions. 212>- For a globally installed bundle, you can directly call the bundle using an environment variable or reference the bundle using the **$\{key\}/tool\_name** parameter when running the **hpm config set key value** command. For example: 213>``` 214>hpm i -g @ohos/opensource/gn 215>hpm config BUILD_SYS_GN ~/.hpm/global/ohos_bundles/opensource/gn 216>``` 217>You can edit the build script in the **bundle.json** file as follows: 218>``` 219>"scripts": { 220> "build": "${BUILD_SYS_GN}/gn --version" 221> }, 222>``` 223>Then, you can run the **hpm build** command to call GN functions. 224 225## Compiling a Bundle<a name="section136732148541"></a> 226 227If the bundle code can be independently compiled once you finish coding, you can configure build tools and scripts to generate binary files. 228 229The hpm supports command integration so that you can select any build tool \(such as **make**, **gcc**, and **gn**\) suitable for your project. You only need to define the **build** command in the **scripts** in the **bundle.json** file of your project, and then you run the hpm command **build** to perform building. 230 231## Defining the Build Script<a name="section10274147111610"></a> 232 233This section uses how to build an executable file **helloworld** in the **app** directory as an example. 234 235``` 236app 237├── BUILD.gn 238├── include 239│ └── helloworld.h 240└── src 241 └── helloworld.c 242``` 243 244Create a **BUILD.gn** file in the same directory as **helloworld.c**. 245 246``` 247touch BUILD.gn 248vim BUILD.gn 249``` 250 251The following is an example of **BUILD.gn** for your reference: 252 253``` 254executable("hello_world") { 255 sources = [ 256 "src/helloworld.c" 257 ] 258 259 include_dirs = [ 260 "include" 261 ] 262} 263``` 264 265> **NOTE:** 266>- **executable** is a built-in template of **gn**. You can run the **gn help executable** command to view how to use this template. 267>- **sources** represents the source code path, and **include\_dirs** represents the header file path. 268 269## Executing the Build Script<a name="section879301916172"></a> 270 271Run the following command: 272 273``` 274hpm build 275``` 276 277After all building operations are complete, the message "build succeed" is displayed. You need to check the building result. 278 279 280 281## Defining a Distribution<a name="section413216495619"></a> 282 283This process states the dependent bundles and how to compile and link the bundles to generate image files. 284 285This section uses the hb compilation framework as an example. 286 287## Defining Scripts<a name="section11503171219190"></a> 288 289An example definition in the **bundle.json** file is as follows: 290 291\{ 292 293"name": "@your/dist\_name", 294 295"version": "2.2.0", 296 297"publishAs": "distribution", 298 299"description": "describe it", 300 301"scripts": \{ 302 303"config\_hb": "hb set -root $DEP\_BUNDLE\_BASE", 304 305"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" 306 307\}, 308 309"envs": \{ 310 311"debug": false 312 313\}, 314 315"dirs": \{ 316 317"scripts": "scripts/\*" 318 319\}, 320 321"dependencies": \{ 322 323"@ohos/build\_lite": "2.2.0", 324 325"@ohos/gn": "1.1.1", 326 327"@ohos/llvm": "1.1.1", 328 329"@ohos/hc\_gen": "1.1.0", 330 331"@ohos/ninja": "1.1.0", 332 333... 334 335\}, 336 337"ohos": \{ 338 339"os": "2.2-Beta", 340 341"board": "hi3516", 342 343"kernel": "liteos-a" 344 345\}, 346 347"keywords": \[ "hispark", "hi3516" \], 348 349"repository": "https://gitee.com/openharmony/your-project", 350 351"license": "Apache V2" 352 353\} 354 355## Building a Distribution<a name="section4694125521912"></a> 356 357Run the following command in the root directory of the current distribution: 358 359``` 360hpm dist 361``` 362 363The **hpm-cli** tool automatically starts compilation. After the compilation is complete, an image file will be generated, as shown below: 364 365``` 366out 367|-xxdist.img 368|-xx.file 369``` 370 371Burning 372 373The build result of the distribution can be burnt into devices, for example, by using the **hiburn** tool. You need to configure burning parameters in the **bundle.json** file of the distribution. 374 375``` 376"scripts": { 377 "flash": "{$DEP_HIBURN}/hiburn" 378}, 379``` 380 381Set the path of the **hiburn** tool and set burning parameters. For details, see the **hiburn** tool guide. 382 383``` 384hpm config set DEP_HIBURN {hiburn_path} 385hpm run flash 386``` 387 388> **NOTE:** 389>The preceding example describes only how to define the **bundle.json** file. The burning tool is subject to the actual development board. 390 391
