1# Module 2## Configuration Rules 3 4The Compilation and Building subsystem implements compilation and packaging by module, component, and product. A module is a 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 provides customized GN templates to configure modules. For details about the GN basics, see [GN Reference](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# Rust templates 27ohos_rust_executable 28ohos_rust_shared_library 29ohos_rust_static_library 30ohos_rust_proc_macro 31ohos_rust_shared_ffi 32ohos_rust_static_ffi 33ohos_rust_cargo_crate 34ohos_rust_systemtest 35ohos_rust_unittest 36 37# Other templates 38# Configuration file 39ohos_prebuilt_etc 40 41# SA profile 42ohos_sa_profile 43``` 44 45You are advised to use OpenHarmony custom templates. 46 47### C/C++ Template Example 48 49The path of the .gni file of the template starting with **ohos** is **openharmony/build/templates/cxx/cxx.gni**. 50 51**ohos_shared_library** example: 52 53```shell 54import("//build/ohos.gni") 55ohos_shared_library("helloworld") { 56 sources = ["file"] 57 include_dirs = [] # If there are duplicate header files, the header file defined earlier takes precedence over the file defined later. 58 cflags = [] # If there are duplicate or conflict settings, the settings in cflags take effect. 59 cflags_c = [] 60 cflags_cc = [] 61 ldflags = [] # If there are duplicate or conflict definitions, the settings in ohos_template take effect. 62 configs = [] 63 deps = [] # Dependent modules that belong to the same component. 64 65 external_deps = [ # Dependent modules that belong to different components. 66 "part_name:module_name", # The value is in the Component_name:Module_name format. 67 ] # The dependent modules must be declared in inner_kits by the dependent component. 68 69 output_name = [string] # Name of the module output. 70 output_extension = [] # Extension name of the module. 71 module_install_dir = "" # Module installation directory in /system/lib64 or /system/lib. 72 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. 73 74 part_name = "" # Component name. This parameter is mandatory. 75 output_dir 76 77 # Sanitizer configuration. Each item is optional, and is false or left unspecified by default. 78 sanitize = { 79 # Sanitizer settings 80 cfi = [boolean] # Whether to enable the control-flow integrity (CFI) check. 81 cfi_cross_dso = [boolean] # Whether to enable the cross-DSO CFI check. 82 integer_overflow = [boolean] # Whether to enable the integer overflow check. 83 boundary_sanitize = [boolean] # Whether to enable the boundary check. 84 ubsan = [boolean] # Whether to enable some Undefined Behavior Sanitizer (UBSAN) options. 85 all_ubsan = [boolean] # Whether to enable all UBSAN options. 86 ... 87 88 debug = [boolean] # Whether to enable the debug mode. 89 blocklist = [string] # Path of the blocklist. 90 } 91 92 testonly = [boolean] 93 license_as_sources = [] 94 license_file = [] # A .txt file. 95 remove_configs = [] 96 no_default_deps = [] 97 install_images = [] 98 install_enable = [boolean] 99 symlink_target_name = [] 100 version_script = [] 101 use_exceptions = [] 102} 103``` 104 105**ohos_static_library** example 106 107```shell 108import("//build/ohos.gni") 109ohos_static_library("helloworld") { 110 sources = ["file"] # .c files. 111 include_dirs = ["dir"] # Directories to be included. 112 configs = [] # Configuration. 113 deps = [] # Dependent modules that belong to the same component. 114 part_name = "" # Component name. 115 subsystem_name = "" # Subsystem name. 116 cflags = [] 117 118 external_deps = [ # Dependent modules that belong to different components. 119 "part_name:module_name", # The value is in the Component_name:Module_name format. 120 ] # The dependent modules must be declared in inner_kits by the dependent component. 121 122 lib_dirs = [] 123 public_configs = [] 124 125 # Sanitizer configuration. Each item is optional, and is false or left unspecified by default. 126 sanitize = { 127 # Sanitizer settings 128 cfi = [boolean] # Whether to enable the control-flow integrity (CFI) check. 129 cfi_cross_dso = [boolean] # Whether to enable the cross-DSO CFI check. 130 integer_overflow = [boolean] # Whether to enable the integer overflow check. 131 boundary_sanitize = [boolean] # Whether to enable the boundary check. 132 ubsan = [boolean] # Whether to enable some Undefined Behavior Sanitizer (UBSAN) options. 133 all_ubsan = [boolean] # Whether to enable all UBSAN options. 134 ... 135 136 debug = [boolean] # Whether to enable the debug mode. 137 blocklist = [string] # Path of the blocklist. 138 } 139 140 remove_configs = [] 141 no_default_deps = [] 142 license_file = [] # A .txt file. 143 license_as_sources = [] 144 use_exceptions = [] 145} 146``` 147 148**ohos_executable** example: 149 150```shell 151import("//build/ohos.gni") 152ohos_executable("helloworld") { 153 configs = [] # Configuration. 154 part_name = "" # Component name. 155 subsystem_name = "" # Subsystem name. 156 deps = [] # Dependent modules that belong to the same component. 157 158 external_deps = [ # Dependent modules that belong to different components. 159 "part_name:module_name", # The value is in the Component_name:Module_name format. 160 ] # The dependent modules must be declared in inner_kits by the dependent component. 161 ohos_test = [] 162 test_output_dir = [] 163 164 # Sanitizer configuration. Each item is optional, and is false or left unspecified by default. 165 sanitize = { 166 # Sanitizer settings 167 cfi = [boolean] # Whether to enable the control-flow integrity (CFI) check. 168 cfi_cross_dso = [boolean] # Whether to enable the cross-DSO CFI check. 169 integer_overflow = [boolean] # Whether to enable the integer overflow check. 170 boundary_sanitize = [boolean] # Whether to enable the boundary check. 171 ubsan = [boolean] # Whether to enable some Undefined Behavior Sanitizer (UBSAN) options. 172 all_ubsan = [boolean] # Whether to enable all UBSAN options. 173 ... 174 175 debug = [boolean] # Whether to enable the debug mode. 176 blocklist = [string] # Path of the blocklist. 177 } 178 179 testonly = [boolean] 180 license_as_sources = [] 181 license_file = [] # A .txt file. 182 remove_configs = [] 183 static_link = [] 184 install_images = [] 185 module_install_dir = "" # Module installation directory, starting from system/ or vendor/. 186 relative_install_dir = "" 187 symlink_target_name = [] 188 output_dir = [directory] # Directory in which output files are located. 189 install_enable = [boolean] 190 version_script = [] 191 use_exceptions = [] 192} 193``` 194 195**ohos_source_set** example 196 197```shell 198import("//build/ohos.gni") 199ohos_source_set("helloworld") { 200 sources = ["file"] # .c files. 201 include_dirs = [] # Directories to be included. 202 configs = [] # Configuration. 203 public = [] # .h header files. 204 defines = [] 205 public_configs = [] 206 part_name = "" # Component name. 207 subsystem_name = "" # Subsystem name. 208 deps = [] # Dependent modules that belong to the same component. 209 210 external_deps = [ # Dependent modules that belong to different components. 211 "part_name:module_name", # The value is in the Component_name:Module_name format. 212 ] # The dependent modules must be declared in inner_kits by the dependent component. 213 214 # Sanitizer configuration. Each item is optional, and is false or left unspecified by default. 215 sanitize = { 216 # Sanitizer settings 217 cfi = [boolean] # Whether to enable the control-flow integrity (CFI) check. 218 cfi_cross_dso = [boolean] # Whether to enable the cross-DSO CFI check. 219 integer_overflow = [boolean] # Whether to enable the integer overflow check. 220 boundary_sanitize = [boolean] # Whether to enable the boundary check. 221 ubsan = [boolean] # Whether to enable some Undefined Behavior Sanitizer (UBSAN) options. 222 all_ubsan = [boolean] # Whether to enable all UBSAN options. 223 ... 224 225 debug = [boolean] # Whether to enable the debug mode. 226 blocklist = [string] # Path of the blocklist. 227 } 228 229 testonly = [boolean] 230 license_as_sources = [] 231 license_file = [] 232 remove_configs = [] 233 no_default_deps = [] 234 license_file = [] # A .txt file. 235 license_as_sources = [] 236 use_exceptions = [] 237} 238``` 239 240> **NOTE** 241> 242> - Only **sources** and **part_name** are mandatory. 243> - For details about the Sanitizer configuration, see [Using Sanitizer](subsys-build-reference.md#using-sanitizer). 244 245 246 247### Prebuilt Template Example 248 249The path of the .gni file of the prebuilt templates is **openharmony/build/templates/cxx/prebuilt.gni**. 250 251**ohos_prebuilt_executable** example 252 253```shell 254import("//build/ohos.gni") 255ohos_prebuilt_executable("helloworld") { 256 source = "file" # Source. 257 output = [] 258 install_enable = [boolean] 259 260 deps = [] # Dependent modules that belong to the same component. 261 public_configs = [] 262 subsystem_name = "" # Subsystem name. 263 part_name = "" # Component name. 264 265 testonly = [boolean] 266 visibility = [] 267 268 install_images = [] 269 module_install_dir = "" # Module installation directory, starting from system/ or vendor/. 270 relative_install_dir = "" # Relative module installation directory (relative to system/etc). If module_install_dir is configured, the parameter does not take effect. 271 symlink_target_name = [] 272 273 274 license_file = [] # A .txt file. 275 license_as_sources = [] 276} 277``` 278 279**ohos_prebuilt_shared_library** example 280 281```shell 282import("//build/ohos.gni") 283ohos_prebuilt_shared_library("helloworld") { 284 source = "file" # Source file, normally with a file name extension .so. 285 output = [] 286 install_enable = [boolean] 287 288 deps = [] # Dependent modules that belong to the same component. 289 public_configs = [] 290 subsystem_name = "" # Subsystem name. 291 part_name = "" # Component name. 292 293 testonly = [boolean] 294 visibility = [] 295 296 install_images = [] 297 module_install_dir = "" # Module installation directory, starting from system/ or vendor/. 298 relative_install_dir = "" # Relative module installation directory (relative to system/etc). If module_install_dir is configured, the parameter does not take effect. 299 symlink_target_name = [string] 300 301 302 license_file = [string] # A .txt file. 303 license_as_sources = [] 304} 305``` 306 307**ohos_prebuilt_static_library** example 308 309```shell 310import("//build/ohos.gni") 311ohos_prebuilt_static_library("helloworld") { 312 source = "file" # Source file, normally with a file name extension .so. 313 output = [] 314 315 deps = [] # Dependent modules that belong to the same component. 316 public_configs = [] 317 subsystem_name = "" # Subsystem name. 318 part_name = "" # Component name. 319 320 testonly = [boolean] 321 visibility = [] 322 323 license_file = [string] # A .txt file. 324 license_as_sources = [] 325} 326``` 327 328> **NOTE**<br> Only **sources** and **part_name** are mandatory. 329 330### HAP Templates 331 332For details about the HAP templates, see [HAP Build Guide](subsys-build-gn-hap-compilation-guide.md). 333 334### Rust Templates 335 336For details about the Rust templates, see [Rust Module Configuration Rules and Guide](subsys-build-rust-compilation.md). 337 338### Other Templates 339 340**ohos_prebuilt_etc** example: 341 342```shell 343import("//build/ohos.gni") 344ohos_prebuilt_etc("helloworld") { 345 # The most common attributes of the ohos_prebuilt_etc template. 346 source = "file" # Single source file. 347 module_install_dir = "" # Module installation directory, starting from system/ or vendor/. 348 subsystem_name = ""# Subsystem name. 349 part_name = "" # Component name. This parameter is mandatory. 350 install_images = [] 351 relative_install_dir = "" # Relative module installation directory (relative to system/etc). If module_install_dir is configured, the parameter does not take effect. 352 353 # Uncommon attributes of the ohos_prebuilt_etc template: 354 deps = [] # Dependent modules that belong to the same component. 355 testonly = [boolean] 356 visibility = [] 357 public_configs = [] 358 symlink_target_name = [string] 359 license_file = [string] 360 license_as_sources = [] 361} 362``` 363 364**ohos_sa_profile** example: 365 366```shell 367import("//build/ohos.gni") 368ohos_sa_profile("helloworld") { 369 sources = [".xml"] # .xml file. 370 part_name = "" # Component name. 371 subsystem_name = "" # Subsystem name. 372} 373``` 374 375> **NOTE** 376> 377> Only **sources** and **part_name** are mandatory. 378 379 380 381## Adding and Building a Module 382 383The following figure shows the logic for adding a module. Generally, you need to add a module to a component of a subsystem. If there is no subsystem or component, you must add the subsystem and component first. Note that the chip solution is a special component and does not have a subsystem. 384 385- Add a module to an existing component. 386 387- Add a module to a new component. 388 389- Add a module to a new subsystem. 390 391  392 393**Adding a Module to an Existing Component** 394 3951. Configure the **BUILD.gn** file in the module directory and select the GN template. 396 3972. Modify the **bundle.json** file. 398 399 ```shell 400 { 401 "name": "@ohos/<component_name>, # HPM component name, in the "@Organization/Component_name" format. 402 "description": "xxxxxxxxxxxxxxxxxxx", # Description of the component functions. 403 "version": "3.1", # Version, which must be the same as the version of OpenHarmony. 404 "license": "MIT", # Component license. 405 "publishAs": "code-segment", # HPM package release mode. The default value is code-segment. 406 "segment": { 407 "destPath": "third_party/nghttp2" 408 }, # Code restoration path (source code path) set when publishAs is code-segment. 409 "dirs": {}, # Directory structure of the HPM package. This field is mandatory and can be left empty. 410 "scripts": {}, # Scripts to be executed. This field is mandatory and can be left empty. 411 "licensePath": "COPYING", 412 "readmePath": { 413 "en": "README.rst" 414 }, 415 "component": { # Component attributes. 416 "name": "<component_name>", # Component name. 417 "subsystem": "", # Subsystem to which the component belongs. 418 "syscap": [], # System capabilities provided by the component for applications. 419 "features": [], # List of configurable features of the component. Generally, this parameter corresponds to sub_component in build. 420 "adapted_system_type": [], # Types of adapted systems. The value can be mini, small, standard, or their combinations. 421 "rom": "xxxKB" # ROM baseline. If there is no baseline, enter the current value. 422 "ram": "xxxKB", # RAM baseline. If there is no baseline, enter the current value. 423 "deps": { 424 "components": [ # Other components on which this component depends. 425 "third_party": [ # Third-party open-source software on which this component depends. 426 }, 427 428 "build": { # Build-related configuration. 429 "sub_component": [ 430 "//foundation/arkui/napi:napi_packages", # Existing module 1. 431 "//foundation/arkui/napi:napi_packages_ndk" # Existing module 2. 432 "//foundation/arkui/napi:new" # Module to add. 433 ], # Component build entry. Configure the module here. 434 "inner_kits": [], # APIs between components. 435 "test": [] # Entry for building the component's test cases. 436 } 437 } 438 } 439 ``` 440 441 > **NOTE**<br>The **bundle.json** file must be in the folder of the corresponding subsystem. 442 4433. Start the build and check whether a .so file or binary file is generated. 444 445**Creating a Component and Adding a Module** 446 4471. 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. 448 4492. Create a **bundle.json** file in the folder of the corresponding subsystem. 450 4513. Add the new component to the end of existing components in **vendor/{product_company}/{product-name}/config.json**. 452 453 ```shell 454 "subsystems": [ 455 { 456 "subsystem": "Subsystem to which the component belongs", 457 "components": [ 458 {"component": "Component 1 name", "features":[]}, # Existing component 1 in the subsystem 459 { "component": "Component 2 name", "features":[] }, # Existing component 2 in the subsystem 460 {"component": "New component name", "features":[]} # New component in the subsystem 461 ] 462 }, 463 . 464 ] 465 ``` 466 4674. Start the build and check whether a .so file or binary file is generated. 468 469 470**Creating a Subsystem and Adding a Module** 471 4721. 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." 473 4742. 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." 475 4763. Modify the **subsystem_config.json** file in the **build** directory. 477 478 ```shell 479 { 480 "Subsystem 1 name": { # Existing subsystem 1 481 "path": "Subsystem 1 directory", 482 "name": "Subsystem 1 name" 483 }, 484 "Subsystem 2 name": { # Existing subsystem 2 485 "path": "Subsystem 2 directory", 486 "name": "Subsystem 2 name" 487 }, 488 "Subsystem name new": { # Subsystem to add 489 "path": "New subsystem directory", 490 "name": "New subsystem name" 491 }, 492 493 } 494 ``` 495 496 The **subsystem_config.json** file defines the subsystems and their directories. When adding a subsystem, specify **path** and **name** for the subsystem. 497 4984. 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. 499 500 ```shell 501 "subsystems": [ 502 { 503 "subsystem": "arkui", # Name of the existing subsystem 504 "components": [ # All components of the subsystem 505 { 506 "component": "ace_engine_standard", # Name of the existing component 507 "features": [] 508 }, 509 { 510 "component": "napi", # Name of the existing component 511 "features": [] 512 } 513 { 514 "component": "component_new1", # Name of the new component to add 515 "features": [] 516 } 517 ] 518 }, 519 { 520 "subsystem": "subsystem_new", # Name of the new subsystem to add. 521 "components": [ 522 { 523 "component": "component_new2", # Name of the component to be added to the new subsystem 524 "features": [] 525 } 526 ] 527 }, 528 529 ] 530 ``` 531 5324. Start the build and check whether a .so file or binary file is generated. 533 534 535**Building a Module** 536 537You 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: 538 539Run the **--build-target** *Module_name* command to build a module separately. 540 541 ```shell 542 ./build.sh --build-target Module_name 543 ``` 544 545Build a product. For example, to build hispark_taurus_standard, run the following command: 546 547 ```shell 548 ./build.sh --product-name hispark_taurus_standard --build-target Module_name --ccache 549 ``` 550 551Build the component to which the module belongs. 552 553 ```shell 554 ./build.sh --product-name hispark_taurus_standard --build-target musl --build-target Module_name --ccache 555 ``` 556
