1# Module 2## Configuration Rules 3 4The Compilation and Building subsystem implements compilation and packaging by module, component, and product. A module is an target to build. It can be a dynamic library, static library, configuration file, or prebuilt module. A module must belong to a component and can belong to only one component. OpenHarmony uses customized GN templates to configure modules. For details about the GN basics, see https://gn.googlesource.com/gn/+/main/docs/reference.md. 5 6The common templates for module configuration are as follows: 7 8``` 9# C/C++ templates 10ohos_shared_library 11ohos_static_library 12ohos_executable 13ohos_source_set 14 15# Prebuilt templates 16ohos_prebuilt_executable 17ohos_prebuilt_shared_library 18ohos_prebuilt_static_library 19 20# HAP templates 21ohos_hap 22ohos_app_scope 23ohos_js_assets 24ohos_resources 25 26# Other templates 27# Configuration file 28ohos_prebuild_etc 29 30# SA profile 31ohos_sa_profile 32``` 33 34You are recommended to use the OpenHarmony customized templates. 35 36### C/C++ Template Example 37 38The .gni file corresponding to the templates starting with **ohos** is located in **openharmony/build/templates/cxx/cxx.gni**. 39 40**ohos_shared_library** example: 41 42```shell 43import("//build/ohos.gni") 44ohos_shared_library("helloworld") { 45 sources = ["file"] 46 include_dirs = [] # If there are duplicate header files, the header files defined earlier take effect. 47 cflags = [] # If there are duplicate or conflict settings, the settings in cflags take effect. 48 cflags_c = [] 49 cflags_cc = [] 50 ldflags = [] # If there are duplicate or conflict definitions, the settings in ohos_template take effect. 51 configs = [] 52 deps = [] # Define dependent modules that belong to the same component. 53 54 external_deps = [ # Define dependent modules that belong to different components. 55 "part_name:module_name", # The value is in the Component_name:Module_name format. 56 ] # The dependent modules must be declared in inner_kits by the dependent component. 57 58 output_name = [string] # Name of the module output. 59 output_extension = [] # Extension name of the module. 60 module_install_dir = [] # Module installation directory. The default directory is /system/lib64 or /system/lib. Specify the directory from system/ or vendor/. 61 relative_install_dir = [] # Relative module installation directory (relative to /system/lib64 or /system/lib). If module_install_dir is configured, the parameter does not take effect. 62 63 part_name = [string] # (Mandatory) Component name. 64 output_dir 65 66 # Sanitizer variables 67 cfi = [boolean] 68 scs = [boolean] 69 scudo = [] 70 ubsan = [] 71 boundary_sanitize = [] 72 integer_overflow_sanitize = [] 73 74 testonly = [boolean] 75 license_as_sources = [] 76 license_file = [] # A .txt file. 77 remove_configs = [] 78 no_default_deps = [] 79 install_images = [] 80 install_enable = [boolean] 81 symlink_target_name = [] 82 version_script = [] 83 use_exceptions = [] 84} 85``` 86 87**ohos_static_library** example: 88 89```shell 90import("//build/ohos.gni") 91ohos_static_library("helloworld") { 92 sources = ["file"] # Source code in .c format. 93 include_dirs = ["dir"] # Directories to be included. 94 configs = [] # Configuration. 95 deps = [] # Define dependent modules that belong to the same component. 96 part_name = [string] # Component name. 97 subsystem_name = [string] # Subsystem name. 98 cflags = [] 99 100 external_deps = [ # Define dependent modules that belong to different components. 101 "part_name:module_name", # The value is in the Component_name:Module_name format. 102 ] # The dependent modules must be declared in inner_kits by the dependent component. 103 104 lib_dirs = [] 105 public_configs = [] 106 107 # Sanitizer variables 108 cfi = [boolean] 109 scs = [boolean] 110 scudo = [] 111 ubsan = [] 112 boundary_sanitize = [] 113 integer_overflow_sanitize = [] 114 115 remove_configs = [] 116 no_default_deps = [] 117 license_file = [] # A .txt file. 118 license_as_sources = [] 119 use_exceptions = [] 120} 121``` 122 123**ohos_executable** example: 124 125```shell 126import("//build/ohos.gni") 127ohos_executable("helloworld") { 128 configs = [] # Configuration. 129 part_name = [string] # Component name. 130 subsystem_name = [string] # Subsystem name. 131 deps = [] # Define dependent modules that belong to the same component. 132 133 external_deps = [ # Define dependent modules that belong to different components. 134 "part_name:module_name", # The value is in the Component_name:Module_name format. 135 ] # The dependent modules must be declared in inner_kits by the dependent component. 136 ohos_test = [] 137 test_output_dir = [] 138 139 # Sanitizer variables 140 cfi = [boolean] 141 scs = [boolean] 142 scudo = [] 143 ubsan = [] 144 boundary_sanitize = [] 145 integer_overflow_sanitize = [] 146 147 testonly = [boolean] 148 license_as_sources = [] 149 license_file = [] # A .txt file. 150 remove_configs = [] 151 static_link = [] 152 install_images = [] 153 module_install_dir = [] # Module installation directory, starting from system/ or vendor/. 154 relative_install_dir = [] 155 symlink_target_name = [] 156 output_dir = [directory] # Directory in which output files are located. 157 install_enable = [boolean] 158 version_script = [] 159 use_exceptions = [] 160} 161``` 162 163**ohos_source_set** example: 164 165```shell 166import("//build/ohos.gni") 167ohos_source_set("helloworld") { 168 sources = ["file"] # Source code in .c format. 169 include_dirs = [] # Directories to be included. 170 configs = [] # Configuration. 171 public = [] # Header files. 172 defines = [] 173 public_configs = [] 174 part_name = [string] # Component name. 175 subsystem_name = [string] # Subsystem name. 176 deps = [] # Define dependent modules that belong to the same component. 177 178 external_deps = [ # Define dependent modules that belong to different components. 179 "part_name:module_name", # The value is in the Component_name:Module_name format. 180 ] # The dependent modules must be declared in inner_kits by the dependent component. 181 182 # Sanitizer variables 183 cfi = [boolean] 184 scs = [boolean] 185 scudo = [] 186 ubsan = [] 187 boundary_sanitize = [] 188 integer_overflow_sanitize = [] 189 190 testonly = [boolean] 191 license_as_sources = [] 192 license_file = [] 193 remove_configs = [] 194 no_default_deps = [] 195 license_file = [] # A .txt file. 196 license_as_sources = [] 197 use_exceptions = [] 198} 199``` 200 201 **NOTE**<br>Only **sources** and **part_name** are mandatory. 202 203### Prebuilt Template Example 204 205The .gni file of the prebuilt templates is located in **openharmony/build/templates/cxx/prebuilt.gni**. 206 207**ohos_prebuilt_executable** example: 208 209```shell 210import("//build/ohos.gni") 211ohos_prebuilt_executable("helloworld") { 212 sources = ["file"] # Source. 213 output = [] 214 install_enable = [boolean] 215 216 deps = [] # Define dependent modules that belong to the same component. 217 public_configs = [] 218 subsystem_name = [string] # Subsystem name. 219 part_name = [string] # Component name. 220 221 testonly = [boolean] 222 visibility = [] 223 224 install_images = [] 225 module_install_dir = [] # Module installation directory, starting from system/ or vendor/. 226 relative_install_dir = [] # Relative module installation directory (relative to system/etc). If module_install_dir is configured, the parameter does not take effect. 227 symlink_target_name = [] 228 229 230 license_file = [] # A .txt file. 231 license_as_sources = [] 232} 233``` 234 235**ohos_prebuilt_shared_library** example: 236 237```shell 238import("//build/ohos.gni") 239ohos_prebuilt_shared_library("helloworld") { 240 sources = ["file"] # .so files. 241 output = [] 242 install_enable = [boolean] 243 244 deps = [] # Define dependent modules that belong to the same component. 245 public_configs = [] 246 subsystem_name = [string] # Subsystem name. 247 part_name = [string] # Component name. 248 249 testonly = [boolean] 250 visibility = [] 251 252 install_images = [] 253 module_install_dir = [] # Module installation directory, starting from system/ or vendor/. 254 relative_install_dir = [] # Relative module installation directory (relative to system/etc). If module_install_dir is configured, the parameter does not take effect. 255 symlink_target_name = [string] 256 257 258 license_file = [string] # A .txt file. 259 license_as_sources = [] 260} 261``` 262 263**ohos_prebuilt_static_library** example: 264 265```shell 266import("//build/ohos.gni") 267ohos_prebuilt_static_library("helloworld") { 268 sources = ["file"] # .so files. 269 output = [] 270 271 deps = [] # Define dependent modules that belong to the same component. 272 public_configs = [] 273 subsystem_name = [string] # Subsystem name. 274 part_name = [string] # Component name. 275 276 testonly = [boolean] 277 visibility = [] 278 279 license_file = [string] # A .txt file. 280 license_as_sources = [] 281} 282``` 283 284 **NOTE**<br>Only **sources** and **part_name** are mandatory. 285 286### HAP Templates 287 288See [HAP Build Guide](subsys-build-gn-hap-compilation-guide.md). 289 290 291 292### Other Templates 293 294**ohos_prebuilt_etc** example: 295 296```shell 297import("//build/ohos.gni") 298ohos_prebuilt_etc("helloworld") { 299 # The most common attributes of the ohos_prebuilt_etc template. 300 sources = ["file"] 301 module_install_dir = [] # Module installation directory, starting from system/ or vendor/. 302 subsystem_name = [string] # Subsystem name. 303 part_name = [string] # (Mandatory) Component name. 304 install_images = [] 305 relative_install_dir = [] # Relative module installation directory (relative to system/etc). If module_install_dir is configured, the parameter does not take effect. 306 307 # Uncommon attributes of the ohos_prebuilt_etc template: 308 deps = [] # Define dependent modules that belong to the same component. 309 testonly = [boolean] 310 visibility = [] 311 public_configs = [] 312 symlink_target_name = [string] 313 license_file = [string] 314 license_as_sources = [] 315} 316``` 317 318**ohos_sa_profile** example: 319 320```shell 321import("//build/ohos.gni") 322ohos_sa_profile("helloworld") { 323 sources = [".xml"] # .xml file. 324 part_name = [string] # Component name. 325 subsystem_name = [string] # Subsystem name. 326} 327``` 328 329 **NOTE**: Only **sources** and **part_name** are mandatory. 330 331## Adding and Building a Module 332 333The figure below illustrates the process for adding a module. A module belongs to a component, which belongs to a subsystem. Please note that the chipset solution, as a special component, does not have a subsystem. You may need to: 334 335- Add a module to an existing component. 336 337- Add a module to a new component. 338 339- Add a module to a new subsystem. 340 341  342 343**Adding a Module to an Existing Component** 344 3451. Configure the **BUILD.gn** file in the module directory and select the GN template. 346 3472. Modify the **bundle.json** file. 348 349 ```shell 350 { 351 "name": "@ohos/<component_name>, # HPM component name, in the "@Organization/Component_name" format. 352 "description": "xxxxxxxxxxxxxxxxxxx", # Description of the component functions. 353 "version": "3.1", # Version, which must be the same as the version of OpenHarmony. 354 "license": "MIT", # Component license. 355 "publishAs": "code-segment", # HPM package release mode. The default value is code-segment. 356 "segment": { 357 "destPath": "third_party/nghttp2" 358 }, # Code restoration path (source code path) set when publishAs is code-segment. 359 "dirs": {}, # Directory structure of the HPM package. This field is mandatory and can be left empty. 360 "scripts": {}, # Scripts to be executed. This field is mandatory and can be left empty. 361 "licensePath": "COPYING", 362 "readmePath": { 363 "en": "README.rst" 364 }, 365 "component": { # Component attributes. 366 "name": "<component_name>", # Component name. 367 "subsystem": "", # Subsystem to which the component belongs. 368 "syscap": [], # System capabilities provided by the component for applications. 369 "features": [], # List of configurable features of the component. Generally, this parameter corresponds to sub_component in build. 370 "adapted_system_type": [], # Types of adapted systems. The value can be mini, small, standard, or their combinations. 371 "rom": "xxxKB" # ROM baseline. If there is no baseline, enter the current value. 372 "ram": "xxxKB", # RAM baseline. If there is no baseline, enter the current value. 373 "deps": { 374 "components": [ # Other components on which this component depends. 375 "third_party": [ # Third-party open-source software on which this component depends. 376 }, 377 378 "build": { # Build-related configuration. 379 "sub_component": [ 380 "//foundation/arkui/napi:napi_packages", # Existing module 1. 381 "//foundation/arkui/napi:napi_packages_ndk" # Existing module 2. 382 "//foundation/arkui/napi:new" # Module to add. 383 ], # Component build entry. Configure the module here. 384 "inner_kits": [], # APIs between components. 385 "test": [] # Entry for building the component's test cases. 386 } 387 } 388 } 389 ``` 390 391  **NOTE**<br>The **bundle.json** file must be in the folder of the corresponding subsystem. 392 3933. Start the build and check whether a .so file or binary file is generated. 394 395**Creating a Component and Adding a Module** 396 3971. Configure the **BUILD.gn** file in the module directory and select the corresponding GN template. Note that **part_name** in the **BUILD.gn** file is the name of the component to add. 398 3992. Create a **bundle.json** file in the folder of the corresponding subsystem. 400 4013. Add the new component to the end of existing components in **vendor/{product_company}/{product_name}/config.json**. 402 403 ```shell 404 "subsystems": [ 405 { 406 "subsystem": "Subsystem to which the component belongs", 407 "components": [ 408 {"component": "Component 1 name", "features":[]}, # Existing component 1 in the subsystem 409 { "component": "Component 2 name", "features":[] }, # Existing component 2 in the subsystem 410 {"component": "New component name", "features":[]} # New component in the subsystem 411 ] 412 }, 413 . 414 ] 415 ``` 416 4174. Start the build and check whether a .so file or binary file is generated. 418 419 420**Creating a Subsystem and Adding a Module** 421 4221. Configure the **BUILD.gn** file in the module directory and select the corresponding GN template. This step is the same as Step 1 in "Creating a Component and Adding a Module." 423 4242. Create a **bundle.json** file in the folder of the component of the subsystem. This step is the same as Step 2 in "Creating a Component and Adding a Module." 425 4263. Modify the **subsystem_config.json** file in the **build** directory. 427 428 ```shell 429 { 430 "Subsystem 1 name": { # Existing subsystem 1 431 "path": "Subsystem 1 directory", 432 "name": "Subsystem 1 name" 433 }, 434 "Subsystem 2 name": { # Existing subsystem 2 435 "path": "Subsystem 2 directory", 436 "name": "Subsystem 2 name" 437 }, 438 "Subsystem name new": { # Subsystem to add 439 "path": "New subsystem directory", 440 "name": "New subsystem name" 441 }, 442 443 } 444 ``` 445 446 The **subsystem_config.json** file defines the subsystems and their directories. When adding a subsystem, specify **path** and **name** for the subsystem. 447 4484. If **product_name** in the **vendor/{product_company}/{product_name}** directory is **hispark_taurus_standard**, add the new component information to the end of existing components in the **config.json** file. 449 450 ```shell 451 "subsystems": [ 452 { 453 "subsystem": "arkui", # Name of the existing subsystem 454 "components": [ # All components of the subsystem 455 { 456 "component": "ace_engine_standard", # Name of the existing component 457 "features": [] 458 }, 459 { 460 "component": "napi", # Name of the existing component 461 "features": [] 462 } 463 { 464 "component": "component_new1", # Name of the new component to add 465 "features": [] 466 } 467 ] 468 }, 469 { 470 "subsystem": "subsystem_new", # Name of the new subsystem to add 471 "components": [ 472 { 473 "component": "component_new2", # Name of the component to be added to the new subsystem 474 "features": [] 475 } 476 ] 477 }, 478 479 ] 480 ``` 481 4824. Start the build and check whether a .so file or binary file is generated. 483 484**Building a Module** 485 486You can start the build by using the [CLI or hb tool](subsys-build-all.md#build-commands). The following uses the CLI as an example: 487 488You can run the **--build-target** *Module_name* command to build a module separately. 489 490```shell 491./build.sh --build-target Module_name 492``` 493 494You can also build a product. For example, to build hispark_taurus_standard, run the following command: 495 496```shell 497./build.sh --product-name hispark_taurus_standard --build-target Module_name --ccache 498``` 499 500You can also build the component to which the module belongs. 501 502```shell 503./build.sh --product-name hispark_taurus_standard --build-target musl --build-target Module_name --ccache 504``` 505 506
