1# Product 2### Configuration Rules 3 4The product solution is a special component. It is a product built based on a development board. It includes the OS adaptation, component assembly and configuration, startup configuration, and file system configuration. The source code path of a product solution is in the **vendor/{Product_solution_vendor}/{Product_name}** format. 5 6The product solution directory structure is as follows: 7 8```shell 9vendor 10└── company # Product solution vendor 11 ├── product # Product name 12 │ ├── init_configs 13 │ │ ├── etc # Startup configuration of the init process (only required for the Linux kernel) 14 │ │ └── init.cfg # System service startup configuration 15 │ ├── hals # OS adaptation 16 │ ├── BUILD.gn # Product build script 17 │ └── config.json # Product configuration file 18 │ └── fs.yml # File system packaging configuration 19 └── ...... 20``` 21 22>  **NOTE**<br>Directories and files must be created for new products based on the preceding rules. The Compilation and Building subsystem scans the configured products based on the rules. 23 24The key directories and files are described as follows: 25 261. **vendor/company/product/init_configs/etc**<br>This folder contains the rcS, Sxxx, and fstab scripts. The init process runs the rcS, fstab, and S00xxx scripts in sequence before starting system services. The Sxxx script is used to create device nodes and directories, scan device nodes, and change file permissions for the development board and product. These scripts are copied from the **BUILD.gn** file to the **out** directory of the product as required and packaged into the **rootfs** image. 27 282. **vendor/company/product/init_configs/init.cfg**<br>**init.cfg** defines how the init process starts services. Currently, the following commands can be parsed: 29 30 - **start**: starts a service. 31 32 - **mkdir**: creates a folder. 33 34 - **chmod**: changes the permission on a specified directory or file. 35 36 - **chown**: changes the owner group of a specified directory or file. 37 38 - **mount**: mounts a device. 39 40 The fields in the file are described as follows: 41 42 ```shell 43 { 44 "jobs" : [{ # An array of jobs. A job corresponds to a command set. Jobs are executed in the following sequence: pre-init > init > post-init. 45 "name" : "pre-init", 46 "cmds" : [ 47 "mkdir /storage/data", # Create a directory. 48 "chmod 0755 /storage/data", # Modify the permissions. The format of the permission value is 0xxx, for example, 0755. 49 "mkdir /storage/data/log", 50 "chmod 0755 /storage/data/log", 51 "chown 4 4 /storage/data/log", # Change the owner group. The first number is the user ID (UID), and the second number is the group ID (GID). 52 ...... 53 "mount vfat /dev/mmcblock0 /sdcard rw,umask=000" # The command format is mount [File system type] [source] [target] [flags] [data]. 54 # The value of flags can be nodev, noexec, nosuid, or rdonly. 55 ] 56 }, { 57 "name" : "init", 58 "cmds" : [ # Start services based on the sequence in the cmds array. 59 "start shell", # There is only one space between start and the service name. 60 ...... 61 "start service1" 62 ] 63 }, { 64 "name" : "post-init", # Job that is finally executed. Operations performed after the init process is started, for example, mounting a device after the driver initialization). 65 "cmds" : [] 66 } 67 ], 68 "services" : [{ # An array of services. A service corresponds to a process. 69 "name" : "shell", # Service name. 70 "path" : ["/sbin/getty", "-n", "-l", "/bin/sh", "-L", "115200", "ttyS000", "vt100"], # Full path of the executable file. It must start with "path". 71 "uid" : 0, # Process UID, which must be the same as that in the binary file. 72 "gid" : 0, # Process GID, which must be the same as that in the binary file. 73 "once" : 0, # Whether the process is a one-off process. The value 1 indicates a one-off process, and the value 0 indicates the opposite. The init process does not restart the one-off process after the process exits. 74 "importance" : 0, # Whether the process is a key process. The value 1 indicates a key process, and the value 0 indicates the opposite. If a key process exits, the init process will restart the board. 75 "caps" : [4294967295] 76 }, 77 ...... 78 ] 79 } 80 ``` 81 823. **vendor/company/product/init_configs/hals**<br>This folder contains the OS adaptation of the product. For details about the interfaces to be implemented, see readme of each component. 83 844. **vendor/company/product/config.json**<br>The **config.json** file is the main entry for compilation and build. It contains the configuration of the development board, OS components, and kernel. 85 86 The following example shows the **config.json** file of the IP camera developed based on the hispark_taurus board: 87 88 ```shell 89 { 90 "product_name": "ipcamera", # Product name 91 "version": "3.0", # Version of config.json. The value must be 3.0. 92 "type": "small", # System type. The value can be mini, small, or standard. 93 "ohos_version": "OpenHarmony 1.0", # OS version 94 "device_company": "hisilicon", # Chipset vendor 95 "board": "hispark_taurus", # Name of the development board 96 "kernel_type": "liteos_a", # Kernel type 97 "kernel_version": "3.0.0", # Kernel version 98 "subsystems": [ 99 { 100 "subsystem": "aafwk", # Subsystem 101 "components": [ 102 { "component": "ability", "features":[ "enable_ohos_appexecfwk_feature_ability = true" ] } # Selected component and feature configuration 103 ] 104 }, 105 { 106 ...... 107 } 108 ...... 109 More subsystems and components 110 } 111 } 112 ``` 113 1145. **vendor/company/product/fs.yml**<br>The **fs.yml** file defines the process for creating a file system image, for example, **rootfs.img** (user-space root file system) and **userfs.img** (readable and writable file). It consists of multiple lists, and each list corresponds to a file system. The fields are described as follows: 115 116 ```shell 117 fs_dir_name: (mandatory) specifies the name of the file system, for example, rootfs or userfs. 118 fs_dirs: (optional) specifies the mapping between the file directory in the out directory and the system file directory. Each file directory corresponds to a list. 119 source_dir: (optional) specifies the target file directory in the out directory. If this field is not specified, an empty directory will be created in the file system based on target_dir. 120 target_dir: (mandatory) specifies the file directory in the file system. 121 ignore_files: (optional) declares ignored files during the copy operation. 122 dir_mode: (optional) specifies the file directory permissions. The default value is 755. 123 file_mode: (optional) specifies the permissions of all files in the directory. The default value is 555. 124 fs_filemode: (optional) specifies the files that require special permissions. Each file corresponds to a list. 125 file_dir: (mandatory) specifies the detailed file path in the file system. 126 file_mode: (mandatory) declares file permissions. 127 fs_symlink: (optional) specifies the soft link of the file system. 128 fs_make_cmd: (mandatory) creates the file system script. The script provided by the OS is located in the build/lite/make_rootfs directory. Linux, LiteOS, ext4, jffs2, and vfat are supported. Chipset vendors can also customize the script as required. 129 fs_attr: (optional) dynamically adjusts the file system based on configuration items. 130 ``` 131 132 The **fs_symlink** and **fs_make_cmd** fields support the following variables: 133 134 - Code root directory, which corresponds to **{ohos_root_path}** of GN. 135 - **out** directory of the product, which corresponds to **{root_out_dir}** of GN. 136 - File system directory **${fs_dir}**, which consists of variables **${root_path}** and **${fs_dir_name}**. 137 138>  **NOTE**<br>**fs.yml** is optional. You do not need to configure it for devices without a file system. 139 1406. **vendor/company/product/BUILD.gn**<br>**BUILD.gn** provides the entry for product build. It is used to compile the source code of the solution vendor and copy the startup configuration file. The **BUILD.gn** file in the corresponding product directory will be built by default if a product is selected. The following is an example of the **BUILD.gn** file of a product: 141 142 ```shell 143 group("product") { # The name must be the same as the product name (level-3 directory name under the product directory). 144 deps = [] 145 deps += [ "init_configs" ] # Copy init configuration. 146 ... # Others 147 } 148 ``` 149 150### Adding and Building a Product 151 152You can customize a product solution by assembling any chipset solution and components. The procedure is as follows: 153 1541. Create a directory for the product. <br>The following uses the Wi-Fi IoT module on the RTL8720 development board as an example. <br>Run the following command in the root directory of the code: 155 156 ```shell 157 mkdir -p vendor/my_company/wifiiot 158 ``` 159 1602. Configure the product. <br>Create a **config.json** file for the product (for example, wifiiot) in the product directory. <br>The **vendor/my_company/wifiiot/config.json** file is as follows: 161 162 ```shell 163 { 164 "product_name": "wifiiot", # Product name 165 "version": "3.0", # Version of config.json. The value must be 3.0. 166 "type": "small", # System type. The value can be mini, small, or standard. 167 "ohos_version": "OpenHarmony 1.0", # OS version 168 "device_company": "realtek", # Name of the chipset solution vendor 169 "board": "rtl8720", # Name of the development board 170 "kernel_type": "liteos_m", # Kernel type 171 "kernel_version": "3.0.0", # Kernel version 172 "subsystems": [ 173 { 174 "subsystem": "kernel", # Subsystem 175 "components": [ 176 { "component": "liteos_m", "features":[] } # Component and its features 177 ] 178 }, 179 ... 180 { 181 More subsystems and components 182 } 183 ] 184 } 185 ``` 186 187  **NOTE**<br>Before the build, the Compilation and Building subsystem checks the validity of the fields in **config.json**. The **device_company**, **board**, **kernel_type**, and **kernel_version** fields must match the chipset solution, and the **subsystem** and **component** fields must match the component description in **build/lite/components**. 188 1893. Implement OS adaptation APIs. Create the **hals** directory in the product directory and save the source code as well as the build script for OS adaptation in the **hals** directory. 190 1914. Create the **init_configs** directory in the product directory and then the **init.cfg** file in the **init_configs** directory, and configure the system services to be started. 192 1935. (Optional) Configure the init process for the Linux kernel. Create the **etc** directory in the **init_configs** directory, and then create the **init.d** folder and the **fstab** file in the **etc** directory. Then, create the **rcS** and **S***xxx* files in the **init.d** file and edit them based on product requirements. 194 1956. (Optional) Configure the file system image for the development board that supports the file system.<br> Create the **fs.yml** file in the product directory, and configure it as required. A typical **fs.yml** file is as follows: 196 197 ```shell 198 - 199 fs_dir_name: rootfs # Image name 200 fs_dirs: 201 - 202 # Copy the files in the out/my_board/my_product/bin directory to the rootfs/bin directory and ignore the .bin files related to testing. 203 source_dir: bin 204 target_dir: bin 205 ignore_files: 206 - Test.bin 207 - TestSuite.bin 208 - 209 # Copy the files in the out/my_board/my_product/libs directory to the rootfs/lib directory, ignore all .a files, and set the file permissions to 644 and folder permissions to 755. 210 source_dir: libs 211 target_dir: lib 212 ignore_files: 213 - .a 214 dir_mode: 755 215 file_mode: 644 216 - 217 source_dir: usr/lib 218 target_dir: usr/lib 219 ignore_files: 220 - .a 221 dir_mode: 755 222 file_mode: 644 223 - 224 source_dir: config 225 target_dir: etc 226 - 227 source_dir: system 228 target_dir: system 229 - 230 source_dir: sbin 231 target_dir: sbin 232 - 233 source_dir: usr/bin 234 target_dir: usr/bin 235 - 236 source_dir: usr/sbin 237 target_dir: usr/sbin 238 - 239 # Create an empty proc directory. 240 target_dir: proc 241 - 242 target_dir: mnt 243 - 244 target_dir: opt 245 - 246 target_dir: tmp 247 - 248 target_dir: var 249 - 250 target_dir: sys 251 - 252 source_dir: etc 253 target_dir: etc 254 - 255 source_dir: vendor 256 target_dir: vendor 257 - 258 target_dir: storage 259 260 fs_filemode: 261 - 262 file_dir: lib/ld-uClibc-0.9.33.2.so 263 file_mode: 555 264 - 265 file_dir: lib/ld-2.24.so 266 file_mode: 555 267 - 268 file_dir: etc/init.cfg 269 file_mode: 400 270 fs_symlink: 271 - 272 # Create the soft link ld-musl-arm.so.1 -> libc.so in the rootfs/lib directory. 273 source: libc.so 274 link_name: ${fs_dir}/lib/ld-musl-arm.so.1 275 - 276 source: mksh 277 link_name: ${fs_dir}/bin/sh 278 - 279 source: mksh 280 link_name: ${fs_dir}/bin/shell 281 fs_make_cmd: 282 # Run the script to create an ext4 image from rootfs. 283 - ${root_path}/build/lite/make_rootfs/rootfsimg_linux.sh ${fs_dir} ext4 284 - 285 fs_dir_name: userfs 286 fs_dirs: 287 - 288 source_dir: storage/etc 289 target_dir: etc 290 - 291 source_dir: data 292 target_dir: data 293 fs_make_cmd: 294 - ${root_path}/build/lite/make_rootfs/rootfsimg_linux.sh ${fs_dir} ext4 295 ``` 296 2977. (Optional) Configure patches if the product and components need to be patched.<br>Create a **patch.yml** file in the product directory. A typical **patch.yml** file is as follows: 298 299 ```shell 300 # Directory in which the patch is to be installed 301 foundation/communication/dsoftbus: 302 # Directory in which the patch is stored 303 - foundation/communication/dsoftbus/1.patch 304 - foundation/communication/dsoftbus/2.patch 305 third_party/wpa_supplicant: 306 - third_party/wpa_supplicant/1.patch 307 - third_party/wpa_supplicant/2.patch 308 - third_party/wpa_supplicant/3.patch 309 ... 310 ``` 311 312 Add **--patch** when running the **hb build** command. Then, the patch files can be added to the specified directory before the build. 313 314 ```shell 315 hb build -f --patch 316 ``` 317 3188. Write the build script. <br>Create a **BUILD.gn** file in the product directory and write the script. The following **BUILD.gn** file uses the Wi-Fi IoT module in Step 1 as an example: 319 320 ```shell 321 group("wifiiot") { # The target name must be the same as the product name. 322 deps = [] 323 deps += [ "init_configs" ] # Copy init configuration. 324 deps += [ "hals" ] # Add hals. 325 ... # Others 326 } 327 ``` 328 3299. Build the product.<br> You 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. For example, the product name is **hispark_taurus_standard**. Run the following command: 330 331 ``` 332 ./build.sh --product-name hispark_taurus_standard --ccache 333 ``` 334 335 336
