1# Reference 2 3## deps and external_deps 4 5When adding a module, you must declare its dependencies in **BUILD.gn**. **deps** specifies dependent modules in the same component, and **external_deps** specifies dependent modules between components. 6 7**Dependency Types** 8 9 10 11The dependency between modules can be classified into **deps** (left in the figure above) and **external_deps** (right in the figure above). 12 13- **deps**: The dependent module to be added belongs to the same part with the current module. For example, module 2 depends on module 1, and both modules 1 and 2 belong to the same component. 14 15- **external_deps**: The dependent module to be added belongs to another component. For example, module 2 depends on module 1, and modules 1 and 2 belong to different components. 16 17- Example of **deps**: 18 19 ```shell 20 import("//build/ohos.gni") 21 ohos_shared_library("module1") { 22 ... 23 part_name = "part1" # (Mandatory) Name of the component to which the module belongs. 24 ... 25 } 26 ``` 27 28 ```shell 29 import("//build/ohos.gni") 30 ohos_shared_library("module2") { 31 ... 32 deps = [ 33 "GN target of module 1", 34 ... 35 ] # Intra-component dependency 36 part_name = "part1" # (Mandatory) Name of the component to which the module belongs. 37 } 38 ``` 39 40- Example of **external_deps**: 41 42 ```shell 43 import("//build/ohos.gni") 44 ohos_shared_library("module1") { 45 ... 46 part_name = "part1" # (Mandatory) Name of the component to which the module belongs. 47 ... 48 } 49 ``` 50 51 ```shell 52 import("//build/ohos.gni") 53 ohos_shared_library("module2") { 54 ... 55 external_deps = [ 56 "part1:module1", 57 ... 58 ] # Inter-component dependency. The dependent module must be declared in inner_kits by the dependent component. 59 part_name = "part2" # (Mandatory) Name of the component to which the module belongs. 60 } 61 ``` 62 63 > **NOTE**<br>The dependency between components must be written in the format of **Component name:Module name** in **external_deps**. The dependent module must be declared in **inner_kits**. 64 65## Using Sanitizer 66 67When adding a module, you can enable the Sanitizer, such as the integer overflow check and control-flow integrity (CFI), provided by the compiler as required. You can also enable the debug or release mode and configure a blocklist. Each configuration item is optional and **false** by default. You can also leave it empty. 68 69Sanitizer configuration example: 70 71``` shell 72 ohos_shared_library("example") { 73 sanitize = { 74 cfi = true # Enable the CFI check. 75 cfi_cross_dso = true # Enable the cross-DSO CFI check. 76 integer_overflow = true # Enable the integer overflow check. 77 boundary_sanitize = true # Enable the bounds check. 78 ubsan = true # Enable some UBSAN options. 79 all_ubsan = true # Enable all UBSAN options. 80 debug = true # Enable the debug mode, which is disabled by default. 81 blocklist = "./blocklist.txt" # Path of the blocklist. 82 } 83 ... 84 } 85``` 86 87**Supported Sanitizer Types** 88 89Currently, Sanitizers provides the following functions: 90 91- **integer_overflow**: provides check of unsigned integer overflow (unsigned_integer_overflow), check of signed integer overflow (signed_integer_overflow), or both (integer_overflow). 92- CFI: provides CFI and cross-DSO CFI checks. 93- **boundary_sanitize**: provides the bounds check. 94- **ubsan**: checks some Undefined Behavior Sanitizer (UBSAN) options, including **bool**, **integer-divide-by-zero**, **return**, **returns-nonnull-attribute**, **shift-exponent**, **unreachable**, and **vla-bound**. 95- **all_ubsan**: checks all UBSAN options. 96 97**Release and Debug Modes** 98 99**Debug** specifies whether the debug mode or the release mode is used. The default value **false** indicates that the release mode is used. The value **true** explicitly declares the debug mode. The **debug** option takes effect only for the Sanitizer and does not determine whether a module is debuggable. In the build configuration for a module in release version, you are advised to set **debug** to **false** (enable the release mode) or leave it unspecified. 100 101- Debug mode: If debug mode is enabled, abundant error-related information is provided to help locate faults. When an error occurs, the application will be resumed instead of being interrupted to further identify subsequent errors. 102 103- Release mode: If release mode is enabled, the application will be directly interrupted when an error occurs. This can protect the system against errors or maliciously attacks. 104 105 106**Blocklist** 107 108The blocklist specifies the functions or source programs that are not affected by Sanitizer in the module. It prevents benign behavior from being identified as errors or prevents hotspot functions from generating unreasonable and unacceptable overheads. Exercise caution when using this function. 109 110Blocklist example: 111 112``` 113[cfi] 114fun:*([Tt]est|TEST)* 115fun: main 116 117[integer] 118src:example/*.cpp 119``` 120 121 122## Information Collected by the Open Source Software Notice 123 124An open source software notice is a file related to the project open source. It collects license information to comply with open source specifications. 125 126**Information to Collect** 127 128The notice collects only the licenses of the modules packaged in the image. For example, the licenses of the tools (such as Clang, Python, and Ninja) used during the build process are not collected. 129 130A static library itself is not packaged. However, if it is packaged into the system as part of a dynamic library or an executable file, the license of the static library will be collected for completeness. 131 132The final **Notice.txt** file must include all licenses used by the files in the image and the mapping between modules and licenses. 133 134The **Notice.txt** file is located in the **/system/etc/** directory. 135 136**Rules for Collecting Information** 137 138Licenses are collected by priority, which ranges from 1 to 4 in descending order of seniority. 139 1401. Licenses that are directly declared in a module's **BUILD.gn** are given the top priority. The following is an example: 141 142 ```shell 143 ohos_shared_library("example") { 144 ... 145 license_file = "path-to-license-file" 146 ... 147 } 148 ``` 149 1502. If there is no explicitly declared license, the build script searches for the **Readme.OpenSource** file in the directory of **BUILD.gn**, parses the file, and collects the obtained licenses. If the **Readme.OpenSource** file does not contain license information, an error will be reported. 151 1523. If the **Readme.OpenSource** file does not exist, the build script searches for the **License**, **Copyright**, and **Notice** files from the current directory to the root directory of the source code by default. The obtained license information will be used as the licenses of the module. 153 1544. If no license is found, the default license (Apache License 2.0) will be used. 155 156Pay attention to the following: 157 158- For third-party open-source software, such as OpenSSL and ICU, **Readme.OpenSource** must be configured in the source code directory. Check whether **Readme.OpenSource** is in the same directory as **BUILD.gn** and whether the licenses configured in **Readme.OpenSource** are valid. 159- If the source code is not licensed under Apache License 2.0, the corresponding license file must be provided in the source code directory or declared in **license_file** for the module. 160- If the source code file added to **BUILD.gn** is not from the current directory, check whether the license in the repository where the source code file is located is the same as that in the repository of **BUILD.gn**. 161 162## Parameters for Accelerating Local Build 163 164The following parameters can be added to the build command to speed up the build process: 165 166- **--ccache** 167 - Ccache caches the output of C/C++ compilation. If the compilation input remains unchanged the next time, the compilation can be skipped and the output can be taken from the cache. 168 - Installing ccache: 169 - Quick installation: Run the **sudo apt-get install ccache** command. 170 - Download the binary file from the [official website](https://ccache.dev/download.html) and configure the ccache path to the environment variable. 171 - Usage: Run the **./build.sh --product-name** *Product_name* **--ccache** command. 172- **--fast-rebuild** 173 - The compilation process includes preloader -> loader -> GN -> Ninja. If the GN and product configuration files are not modified locally, adding **--fast-rebuild** will start from Ninja directly. 174 - Usage: Run the **./build.sh --product-name** *Product_name* **--fast-rebuild** command. 175- **enable_notice_collection=false** 176 - Adding this parameter can skip the process of collecting the module licenses of the open-source software. 177 - Usage: Run the **./build.sh --product-name** *Product_name* **--gn-args --enable_notice_collection=false --ccache** command. 178- **--build-target** 179 - This parameter specifies the module to compile. You can obtain the module name as follows: 180 - Pay attention to keywords such as **group**, **ohos_shared_library**, and **ohos_executable** in **BUILD.gn**. 181 - Run **./build.sh --product-name** *Product_name* **--build-target** *Module_name* **--build-only-gn** to generate **build.ninja** and locate the related module name in the file. 182 - Usage: Run the **./build.sh --product-name** *Product_name* **--build-target ark_js_host_linux_tools_packages** command. 183 184## Viewing Ninja Build Information 185 186The **out/rk3568/.ninja_log** file records the build start time and end time (ms) of each module. A shorter interval indicates a faster build and higher compilation performance. 187 188The four columns are start time, end time, modified timestamp (mtime), and command hash from left to right. 189 190 191 192You can graphically display the build time as follows: 193 194- Open **build.trace** locally. 195 Decompress **out/rk3568/build.trace.gz** and drag **build.trace** to **chrome://tracing/**. 196- Open **build.trace** at **ci.openharmony.cn/events**. 197 You can open the **build.trace.html** file in each compilation output as follows: 198 1. Click **Success** under **Static Check**. 199 200 2. Click **Output** in the **Output** column. The **build.trace.html** file is displayed in the **build_trace** column on the left. Click the file to open it. 201 202## Customizing the chip_prod Image 203 204### When to Use 205 206The different capabilities for the products in the same chip solution are placed in the **chip_prod** partition. You need to generate the **chip_prod.img** specific to the product. 207 208### Procedure 2091. Configure the **config.json** file. 210 211 In the **config.json** file, add **chipprod_config_path**, which specifies the path of the product definition file. 212 The file is named **chip_product_list.gni**, and in the **chip_product_list = ["productA", "productB", ...]** format. 213 214 Example: 215 216 To customize **chip_prod.img** for **MyProduct**, modify the **//vendor/Product vendor/MyProduct/config.json** as follows: 217 218 ```shell 219 { 220 "product_name": "MyProduct", # Product name. 221 "version": "3.0", # config.json version, which is 3.0. 222 "chipprod_config_path": "", # (Optional) Path of the chipprod configuration file. 223 "subsystems": [ 224 { 225 "subsystem": "arkui", # Subsystem of the product. 226 "components": [ 227 { 228 "component": "ace_engine", 229 "features":[ "ace_engine_feature_enable_web = true", 230 "ace_engine_feature_enable_accessibility = true" ] } 231 ] 232 }, 233 { 234 ... 235 } 236 ... 237 More subsystems and components. 238 } 239 } 240 ``` 241 2422. Configure the module. 243 244 If the configuration file has different product configurations, for example, to generate **chip_prod.img** for product A, you need to configure **install_images** and **module_install_dir** for module compilation. 245 246 The following uses **ohos_prebuilt_executable** as an example: 247 248 ```shell 249 ohos_prebuilt_executable("moduleXXX"){ 250 install_images = [ "chip_prod" ] 251 module_install_dir = "productA/etc/***" # The path must start with productA. 252 } 253 ``` 254 2553. Run the build command. 256```shell 257./build.sh --product-name {product_name} --build-target chip_prod_image 258``` 259 2604. Generate the images. 261 If products A and B are defined (**chip_product_list = ["productA", "productB"]**) and a module is installed in the products, the following images are generated: 262 263 ``` 264 images/productA/chip_prod.img 265 images/productB/chip_prod.img 266 ``` 267
