# Building Adaptation Process<a name="EN-US_TOPIC_0000001153683026"></a>
For details about compilation and building, see [Compilation and Building](../subsystems/subsys-build-mini-lite.md). When adding third-party chips, perform the following steps to complete building adaptation:
## Building Adaptation Process<a name="section2159183845319"></a>
You need to create a directory for the development board. Taking the **RTL8720** development board of SoC provider Realtek for example, the **device/realtek/rtl8720** directory must be created. To complete the building adaptation, perform the following steps:
1. Configure the toolchain and building options.
The **ohos-clang** toolchain is used by default. SoC providers can also customize the configuration based on their development boards. The building-related variables in the building configuration file of the development board are described as follows:
- **kernel\_type**: kernel type used by the development board, for example, **"liteos\_a"**, **"liteos\_m"**, or **"linux"**.
- **kernel\_version**: kernel version used for development, for example, **"4.19"**.
- **board\_cpu**: CPU type of the development board, for example, **"cortex-a7"** or **"riscv32"**.
- **board\_arch**: chip architecture of the development board, for example, **"armv7-a"** or **"rv32imac"**.
- **board\_toolchain**: name of the customized building toolchain used by the development board, for example, **"gcc-arm-none-eabi"**. If this variable is not specified, **ohos-clang** will be used by default.
- **board\_toolchain\_prefix**: prefix of the building toolchain, for example, **"gcc-arm-none-eabi"**.
- **board\_toolchain\_type**: building toolchain type. Currently, GNU compiler collection \(GCC\) and clang are supported, for example, **"gcc"** or **"clang"**.
- **board\_cflags**: building options of the **.c** file configured for the development board.
- **board\_cxx\_flags**: building options of the **.cpp** file configured for the development board.
- **board\_ld\_flags**: link options configured for the development board.
The corresponding **config.gni** file will be loaded based on the development board selected by the product. The variables in this file are globally visible to system components.
Taking the RTL8720 development board of Realtek as an example, the **device/realtek/rtl8720/liteos\_m/config.gni** file is configured as follows:
```
# Kernel type, e.g. "linux", "liteos_a", "liteos_m".
kernel_type = "liteos_m"
# Kernel version.
kernel_version = "3.0.0"
# Board CPU type, e.g. "cortex-a7", "riscv32".
board_cpu = "real-m300"
# Board arch, e.g. "armv7-a", "rv32imac".
board_arch = ""
# Name of the toolchain that is used for system building
# E.g. gcc-arm-none-eabi, arm-linux-harmonyeabi-gcc, ohos-clang, riscv32-unknown-elf.
# Note: The "ohos-clang" toolchain is used by default. You can also customize the toolchain.
board_toolchain = "gcc-arm-none-eabi"
# Path where the toolchain is installed, which can be left blank if the installation path has been added to ~/.bashrc.
2. Edit the building script of the development board.
For a newly added development board, the **BUILD.gn** file that functions as the entry for building must be added to the board directory. Taking the RTL8720 development board of Realtek as an example, the content in the **device/realtek/rtl8720/BUILD.gn** file is as follows:
```
group("rtl8720") {
...
}
```
3. Build and debug the development board.
1. Run the **hb set** command in any directory to set the source code path and the product to build.
2. Run the **hb build** command in the development board directory to start the building.
4. Build and debug the product.
Write the development board and component information to the product configuration file. Fields in the configuration file are as follows:
- **product\_name**: product name, which can be customized. It is recommended that the value be the same as the level-3 directory name under the **vendor** directory.
- **ohos\_version**: OpenHarmony version number, which must be the same as the actual version number.
- **device\_company**: name of the chip solution vendor. It is recommended that the value be the same as the level-2 directory name under the **device** directory.
- **board**: name of the development board. It is recommended that the value be the same as the level-3 directory name under the **device** directory.
- **kernel\_type**: kernel type, which must match the kernel type supported by the development board.
- **kernel\_version**: kernel version, which must match the kernel version supported by the development board.
- **subsystem**: OpenHarmony subsystem selected for the product. For details about the subsystems supported by OpenHarmony, see the descriptions of the subsystems in the **build/lite/components** directory.
- **components**: subsystem-specific components selected for the product. For details about the components supported by the selected subsystem, see the **build/lite/components/_Specific subsystem_.json** file.
- **features**: component-specific features configured for the product. For details about the features supported by the selected component, see the **features** field of the component in **build/lite/components/_Specific subsystem_.json** file.
Taking the Wi-Fi IoT module based on the RTL8720 development board as an example, the **vendor/my\_company/wifiiot/config.json** file is as follows:
```
{
"product_name": "wifiiot", # Product name
"ohos_version": "OpenHarmony 1.0", # In-use OS version
"device_company": "realtek", # Name of the chip solution vendor
"board": "rtl8720", # Name of the development board
"kernel_type": "liteos_m", # Selected kernel type
"kernel_version": "3.0.0", # Selected kernel version
"subsystems": [
{
"subsystem": "kernel", # Selected subsystem
"components": [
{ "component": "liteos_m", "features":[] } # Selected component and its features
]
},
...
{
More subsystems and components
}
]
}
```
# Building Adaptation Process
For details about compilation and building, see [Compilation and Building Guide](../subsystems/subsys-build-all.md). When adding third-party chips, perform the following steps to complete building adaptation:
## Building Adaptation Process
You need to create a directory for the development board. For example, for the RTL8720 development board from SoC provider Realtek, the **device/realtek/rtl8720** directory must be created. To complete the building adaptation, perform the following steps:
1. Configure the toolchain and building options.
The **ohos-clang** toolchain is used by default. SoC providers can also customize the configuration based on their development boards. The building-related variables in the building configuration file of the development board are described as follows:
-**kernel_type**: kernel used by the development board, for example, **"liteos_a"**, **"liteos_m"**, or **"linux"**.
-**kernel_version**: kernel version of the development board, for example, **"4.19"**.
-**board_cpu**: CPU of the development board, for example, **"cortex-a7"** or **"riscv32"**.
-**board_arch**: chipset architecture of the development board, for example, **"armv7-a"** or **"rv32imac"**.
-**board_toolchain**: name of the customized build toolchain used by the development board, for example, **"gcc-arm-none-eabi"**. If this field is not specified, **ohos-clang** will be used.
-**board_toolchain_prefix**: prefix of the build toolchain, for example, **"gcc-arm-none-eabi"**.
-**board_toolchain_type**: build toolchain type. Currently, only GCC (**"gcc"**) and clang (**"clang"**) are supported.
-**board_cflags**: build options of the .c file configured for the development board.
-**board_cxx_flags**: build options of the **.cpp** file configured for the development board.
-**board_ld_flags**: linking options configured for the development board.
The corresponding **config.gni** file will be loaded based on the development board selected by the product. The variables in this file are globally visible to system modules.
The following is an example of the **device/realtek/rtl8720/liteos_m/config.gni** file for the RTL8720 development board:
```
# Kernel type, e.g. "linux", "liteos_a", "liteos_m".
kernel_type = "liteos_m"
# Kernel version.
kernel_version = "3.0.0"
# Board CPU type, e.g. "cortex-a7", "riscv32".
board_cpu = "real-m300"
# Board arch, e.g. "armv7-a", "rv32imac".
board_arch = ""
# Toolchain name used for system compiling.
# E.g. gcc-arm-none-eabi, arm-linux-harmonyeabi-gcc, ohos-clang, riscv32-unknown-elf.
# Note: The default toolchain is "ohos-clang". It's not mandatory if you use the default toochain.
board_toolchain = "gcc-arm-none-eabi"
# The toolchain path installed, it's not mandatory if you have added toolchain path to your ~/.bashrc.
2. Write the build script of the development board.
For a newly added development board, the **BUILD.gn** file that functions as the entry for building must be added to the board directory. The following is an example of the **device/realtek/rtl8720/BUILD.gn** file for the RTL8720 development board:
```
group("rtl8720") {
...
}
```
3. Build and debug the development board.
1. Run the **hb set** command in any directory to set the source code path and the product to build.
2. Run the **hb build** command in the development board directory to start the build.
4. Build and debug the product.
Write the development board and module information to the product configuration file. Fields in the configuration file are as follows:
-**product_name**: product name, which can be customized. It is recommended that the value be the same as the level-3 directory name under the **vendor** directory.
-**ohos_version**: OpenHarmony version number, which must be the same as the actual version number.
-**device_company**: name of the chip solution vendor. It is recommended that the value be the same as the level-2 directory name under the **device** directory.
-**board**: name of the development board. It is recommended that the value be the same as the level-3 directory name under the **device** directory.
-**kernel_type**: kernel type, which must match the kernel type supported by the development board.
-**kernel_version**: kernel version, which must match the kernel version supported by the development board.
-**subsystem**: subsystem selected for the product. For details about the supported subsystem, see the descriptions of the subsystems in the **build/lite/components** directory.
-**components**: subsystem-specific modules selected for the product. For details about the modules supported by the selected subsystem, see the **build/lite/components/*Specific subsystem*.json** file.
-**features**: module-specific features configured for the product. For details about the features supported by the selected module, see the **features** field of the module in **build/lite/components/*Specific subsystem*.json** file.
The following is an example of the **vendor/my_company/wifiiot/config.json** file for the Wi-Fi IoT module on the RTL8720 development board:
```
{
"product_name": "wifiiot", # Product name
"ohos_version": "OpenHarmony 1.0", # OS version
"device_company": "realtek", # Name of the chipset solution vendor
"board": "rtl8720", # Name of the development board
"kernel_type": "liteos_m", # Kernel type
"kernel_version": "3.0.0", # Kernel version
"subsystems": [
{
"subsystem": "kernel", # Subsystem
"components": [
{ "component": "liteos_m", "features":[] } # Module and its features
# Linux Kernel<a name="EN-US_TOPIC_0000001200171987"></a>
# Linux Kernel
## Overview<a name="section6282121355111"></a>
Linux kernel porting involves basic kernel compilation, building, and verification after third-party chipset patches are installed based on the Linux kernel baseline.
The current Linux kernel baseline evolves based on the Linux LTS version 4.19 and incorporates the CVE and bugfix patches. For details, see the [code library](https://gitee.com/openharmony/kernel_linux). The code path for the **repo** project is **kernel/linux-4.19**.
### Bootloader<a name="section19062510518"></a>
You can use the Bootloader provided by the chipset vendor or open-source U-Boot to load the kernel image. For example, you can use [U-Boot](https://gitee.com/openharmony/third_party_u-boot) for the Hi3516D V300 development board.
## Adaptation, Building, Burning, and Startup<a name="section11112101695215"></a>
## Overview
1. Prepare the kernel configuration files, especially the chipset-related configuration files.
Source code directory of the configuration files: **kernel/linux/config/**
Create a **<_YOUR\_CHIP_\>\_small\_defconfig** file, such as **hi3516dv300\_small\_defconfig**, in the **linux-4.19/arch/arm/configs/** directory. The configuration file can be created by combining the general-purpose **small\_common\_defconfig** file and chipset-specific configurations.
2. Prepare the chipset patches.
Linux kernel porting involves basic kernel compilation, building, and verification after third-party chipset patches are installed based on the Linux kernel baseline.
Source code directory of the patch files: **kernel/linux/patches/linux-4.19**
Create a **<_YOUR\_CHIP_\>\_patch** directory by referring to the existing patch directory **hi3516dv300\_small\_patch**, and place the related chipset patches, such as **hdf.patch** \(recommended\), in this directory.
### Basic Information
3. Build the code.
The current Linux kernel baseline evolves based on the Linux LTS version 4.19 and incorporates the CVE and bugfix patches. For details, see the [kernel_linux code repository](https://gitee.com/openharmony/kernel_linux). The code path for the **repo** project is **kernel/linux-4.19**.
In the project directory **kernel/linux/patches/**, after version-level build commands are passed to the **kernel\_module\_build.sh** and **kernel.mk** files, adapt the **patch** and **defconfig** configuration file paths, compiler, chipset architecture, and kernel image format.
Adjust the patches based on build error logs. Typical error scenarios are as follows:
### Bootloader
\(1\) A conflict occurs in installing a patch. In this case, context adaptation is required.
You can use the Bootloader provided by the chipset vendor or open-source U-Boot to load the kernel image. For example, you can use [U-Boot](https://gitee.com/openharmony/third_party_u-boot) for the Hi3516D V300 development board.
\(2\) The build fails due to kernel version mismatch. In this case, kernel adaptation is required, including function implementation adjustment.
>- As in the **kernel.mk** file, patches are applied after the code environment of **kernel/linux-4.19** is copied during compilation and building of the OpenHarmony project. Retain the original code environment of **kernel/linux-4.19** before running the OpenHarmony version-level build command.
>- You can modify the patches in **out/<\*\*\*\>/kernel/linux-4.19**, to which the code environment is copied.
## Adaptation, Building, Burning, and Startup
4. Burn images and start the development board.
1. Prepare the kernel configuration files, especially the chipset-related configuration files.
Source code directory of the configuration files: **kernel/linux/config/**
The burning mode varies according to the development board of the chipset. Pay attention to the size of each burnt image and the configuration of the boot parameters. Below is the U-Boot parameter settings of Hi3516D V300:
Create a **<*YOUR_CHIP*>_small_defconfig** file, such as **hi3516dv300_small_defconfig**, in the **linux-4.19/arch/arm/configs/** directory. The configuration file can be created by combining the general-purpose **small_common_defconfig** file and chipset-specific configurations.
Source code directory of the patch files: **kernel/linux/patches/linux-4.19**
Create a **<*YOUR_CHIP*>_patch** directory by referring to the existing patch directory **hi3516dv300_small_patch**, and place the related chipset patches, such as **hdf.patch** (recommended), in this directory.
3. Start the build.
In the project directory **kernel/linux/patches/**, after version-level build commands are passed to the **kernel_module_build.sh** and **kernel.mk** files, adapt the **patch** and **defconfig** configuration file paths, compiler, chipset architecture, and kernel image format.
Adjust the patches based on build error logs. Typical error scenarios are as follows:
Debug the **init** process, start shell, and run a simple program in the user space to check whether the kernel porting is successful. Below is the OS image structure of the OpenHarmony [small system](../quick-start/quickstart-lite-overview.md) and the Linux user-space program startup process.
(1) A conflict occurs in installing a patch. In this case, context adaptation is required.
**Figure 1** OS image structure and user-space program startup process based on the Linux kernel<aname="fig91631652715"></a>
> - As in the **kernel.mk** file, patches are applied after the code environment of **kernel/linux-4.19** is copied during compilation and building of the OpenHarmony project. Retain the original code environment of **kernel/linux-4.19** before running the OpenHarmony version-level build command.
>
> - You can modify the patches in **out/<\*\*\*>/kernel/linux-4.19**, to which the code environment is copied.
1. Create a root file system image.
4. Burn images and start the development board.
Create a root file system image **rootfs.img** by following instructions in [Adding a Chipset Solution and a Product Solution](../subsystems/subsys-build-all.md). As shown in the preceding figure, the startup process is closely related to the product configuration. You need to complete the following configuration when creating **rootfs.img**:
The burning mode varies according to the development board of the chipset. Pay attention to the size of each burnt image and the configuration of the boot parameters. Below is the U-Boot parameter settings of Hi3516D V300:
- Component configuration
In the product component configuration file **_vendor_/\{_company_\}/\{_product_\}/config.json**, configure the **init\_lite** component of the startup subsystem and the **linux\_4\_1\_9** component of the kernel subsystem.
Modify the system service configuration file **_vendor_/\{_company_\}/\{_product_\}/init\_configs/init\_xxx.cfg** to start the shell service.
## Verification
- File system configuration
Debug the **init** process, start shell, and run a simple program in the user space to check whether the kernel porting is successful. Below is the OS image structure of the OpenHarmony [small system](../quick-start/quickstart-lite-overview.md) and the Linux user-space program startup process.
In the file system configuration file **_vendor_/\{_company_\}/\{_product_\}/fs.yml**, create the **/bin/sh -\> mksh** and **/lib/ld-musl-arm.so.1 -\> libc.so** soft links. These two files are the shell executable program and the c library on which the executable program depends, respectively.
**Figure 1** OS image structure and user-space program startup process based on the Linux kernel
In the **_vendor_/\{_company_\}/\{_product_\}/init\_configs/etc** directory, configure startup settings, including the **fstab**, **rsS**, and **S_xxx_** files. Configure the startup settings as needed.
Based on the preceding process, the recommended verification procedure is as follows:
After the build is complete, check the **rootfs** content in the product compilation output directory to determine whether the generated **rootfs.img** file meets the expectation.
1. Create a root file system image.
Create a root file system image **rootfs.img** by following instructions in [Building Procedures](../subsystems/subsys-build-all.md). As shown in the preceding figure, the startup process is closely related to the product configuration. You need to complete the following configuration when creating **rootfs.img**:
2. Debug the init process and shell.
- Component configuration
In the product component configuration file ***vendor*/{*company*}/{*product*}/config.json**, configure the **init_lite** component of the startup subsystem and the **linux_4_1_9** component of the kernel subsystem.
- System service configuration
Modify the system service configuration file ***vendor*/{*company*}/{*product*}/init_configs/init_xxx.cfg** to start the shell service.
- File system configuration
In the file system configuration file ***vendor*/{*company*}/{*product*}/fs.yml**, create the **/bin/sh -> mksh** and **/lib/ld-musl-arm.so.1 -> libc.so** soft links. These two files are the shell executable program and the c library on which the executable program depends, respectively.
- Startup configuration
In the ***vendor*/{*company*}/{*product*}/init_configs/etc** directory, configure startup settings, including the **fstab**, **rsS**, and **S*xxx*** files. Configure the startup settings as needed.
After the build is complete, check the **rootfs** content in the product compilation output directory to determine whether the generated **rootfs.img** file meets the expectation.
2. Debug the init process and shell.
Burn **rootfs.img** and debug the init process and shell. The burning tools and processes vary according to the development board. Follow the instructions provided by the chipset solution vendor. Before burning **rootfs.img**, ensure that the bootloader and Linux kernel are started properly. When **rootfs.img** is properly mounted by the kernel, the **/bin/init** program is executed, indicating the start of the user space.
Burn **rootfs.img** and debug the init process and shell. The burning tools and processes vary according to the development board. Follow the instructions provided by the chipset solution vendor. Before burning **rootfs.img**, ensure that the bootloader and Linux kernel are started properly. When **rootfs.img** is properly mounted by the kernel, the **/bin/init** program is executed, indicating the start of the user space.
The init process calls the **/etc/init.d/rcS** script. The **rcS** script runs the first command **/bin/mount -a** to load the **fstab** file. After the commands in this file are executed, **rcS** calls the **S_xxx_** scripts in sequence to create and scan for device nodes and configure file permissions.
The init process calls the **/etc/init.d/rcS** script. The **rcS** script runs the first command **/bin/mount -a** to load the **fstab** file. After the commands in this file are executed, **rcS** calls the **S*xxx*** scripts in sequence to create and scan for device nodes and configure file permissions.
Then the init process reads the **init.cfg** system service configuration file and starts the shell as configured. If the preceding process is executed properly, the system enters the shell.
Then the init process reads the **init.cfg** system service configuration file and starts the shell as configured. If the preceding process is executed properly, the system enters the shell.
If the init startup log contains the version number, the init program is started properly:
If the init startup log contains the version number, the init program is started properly:
**Figure 2** Log indicating that the init process is started properly<a name="fig1111661083719"></a>
After entering the shell, run the **ls** command. The following figure shows the information printed over the serial port.
3. Configure the NFS.
**Figure 3** Information printed after the ls command is executed in the shell
After the init process and shell are started, run the following command in the root directory to enable the NFS service. In this example, the server IP address is 192.168.1.22 and the client IP address is 192.168.1.4.
mount -t nfs -o nolock,addr=192.168.1.22 192.168.1.22:/nfs /storage/nfs
```
3. Configure the NFS.
After the init process and shell are started, run the following command in the root directory to enable the NFS service. In this example, the server IP address is 192.168.1.22 and the client IP address is 192.168.1.4.
```
ifconfig eth0 192.168.1.4 netmask 255.255.255.0
mkdir -p /storgage/nfs
mount -t nfs -o nolock,addr=192.168.1.22 192.168.1.22:/nfs /storage/nfs
Set up the basic environment by following instructions in [Setting Up the Hi3861 Development Board Environment](../quick-start/quickstart-lite-steps-hi3861-setting.md). Both the user space and LiteOS Cortex-A kernel space are compiled using the LLVM compiler. If you choose to port the Linux kernel, run the following command to install the gcc-arm-linux-gnueabi cross compiler for compiling the Linux kernel-space image:
Set up the basic environment by following instructions in [Ubuntu Build Environment](../quick-start/quickstart-lite-steps-hi3861-setting.md). Both the user space and LiteOS Cortex-A kernel space are compiled using the LLVM compiler. If you choose to port the Linux kernel, run the following command to install the gcc-arm-linux-gnueabi cross compiler for compiling the Linux kernel-space image:
```
sudo apt-get install gcc-arm-linux-gnueabi
```
## Introduction to the Compilation and Building Subsystem<a name="section354343816319"></a>
To learn more about the compilation and building subsystem, including the compilation and building process, compilation scripts, and building chipset source code or single components, see [Compilation and Building](../subsystems/subsys-build-mini-lite.md).
## Adding a Chipset Solution<a name="section18612153175011"></a>
After learning the compilation framework and setting up the compilation environment, perform the following steps to create a chipset solution:
## Introduction to the Compilation and Building Subsystem
1.<aname="li20894101862"></a>Create a category.
The directory structure is as follows: device/\{_chipset solution vendor_\}/\{_development board_\}. For example, if you are using the hispark\_taurus development board from HiSilicon, create the following directory in the root directory of the code:
```
mkdir -p device/hisilicon/hispark_taurus
```
The chipset solution directory tree is as follows:
```
device
└── company # Chipset solution vendor
└── board # Name of the development board
├── BUILD.gn # Build script
├── hals # Southbound APIs for OS adaptation
├── linux # Linux kernel version (optional)
│ └── config.gni # Build options for the Linux version
└── liteos_a # LiteOS kernel version (optional)
└── config.gni # Build options for the LiteOS Cortex-A version
```
For example, if you are porting the Linux kernel to the hispark\_taurus development board, the directory tree is as follows:
```
device
└── hisilicon
└── hispark_tautus
├── BUILD.gn
├── hals
├── ......
└── linux
└── config.gni
```
After the directory tree is created, store the source code related to the development board in the **hispark\_taurus** directory.
2. Configure the build options of the development board.
You can configure the build options in the **config.gni** file described in [1](#li20894101862). The compilation and building framework will then compile all OS components in the user space based on your configuration. The **config.gni** file contains the following key fields:
```
kernel_type: kernel used by the development board, for example, liteos_a, liteos_m, or linux.
kernel_version: kernel version used by the development board, for example, 4.19.
board_cpu: CPU of the development board, for example, cortex-a7 or riscv32.
board_arch: chipset architecture of the development board, for example, armv7-a or rv32imac.
board_toolchain: name of the customized compiler used by the development board, for example, gcc-arm-none-eabi. If this field is not specified, ohos-clang will be used by default.
board_toolchain_prefix: prefix of the compiler, for example, gcc-arm-none-eabi.
board_toolchain_type: compiler type, for example, gcc or clang. Currently, only GCC and clang are supported.
board_cflags: build options of the .c file configured for the development board.
board_cxx_flags: build options of the .cpp file configured for the development board.
board_ld_flags: link options configured for the development board.
```
For HiSilicon's hispark\_taurus development board, the content in **device/hisilicon/hispark\_taurus/config.gni** is as follows:
```
# Board CPU type, e.g. "cortex-a7", "riscv32".
board_cpu = "cortex-a7"
# Name of the compiler that is used for system building
# E.g. gcc-arm-none-eabi, arm-linux-harmonyeabi-gcc, ohos-clang, riscv32-unknown-elf.
# Note: The "ohos-clang" toolchain is used by default. You can also customize the toolchain.
board_toolchain = "mips-linux-gnu-gcc"
# Path where the toolchain is installed, which can be left blank if the installation path has been added to ~/.bashrc.
# Board storage type, it used for file system generation.
storage_type = "emmc"
```
3. Edit the build script of the development board.
In the **BUILD.gn** file described in step [1](#li20894101862), build code related to the development board, such as code for the on-device driver, on-device interface adaptation \(media and graphics\), and SDK on the development board.
For example, edit the **device/hisilicon/hispark\_taurus/BUILD.gn** file as follows:
```
# It is recommended that the group name be the same as the development board name.
...... # Other compilation units of the development board
]
}
```
To learn more about the Compilation and Building subsystem, including the compilation and building process, build scripts, and directory structure, see [Compilation and Building Guide](../subsystems/subsys-build-all.md).
4. Start building and debugging.
In the directory of the development board, run the **hb set** and **hb build** commands to start building the chipset solution. The compilation framework starts the building with the **BUILD.gn** file in the directory as the entry.
## Adding a Chipset Solution
After learning the compilation framework and setting up the compilation environment, perform the following steps to create a chipset solution:
1. Create a category.
The directory structure is as follows: device/{*chipset solution vendor*}/{*development board*}. For example, if you are using the hispark_taurus development board from HiSilicon, create the following directory in the root directory of the code:
```
mkdir -p device/hisilicon/hispark_taurus
```
The chipset solution directory tree is as follows:
```
device
└── company # Chipset solution vendor
└── board # Name of the development board
├── BUILD.gn # Build script
├── hals # OS device API adaptation
├── linux # (Optional) Linux kernel version
│ └── config.gni # Linux build configuration
└── liteos_a # (Optional) LiteOS kernel version
└── config.gni # LiteOS_A build configuration
```
For example, if you are porting the Linux kernel to the hispark_taurus development board, the directory tree is as follows:
```
device
└── hisilicon
└── hispark_taurus
├── BUILD.gn
├── hals
├── ......
└── linux
└── config.gni
```
After the directory tree is created, store the source code related to the development board in the **hispark_taurus** directory.
2. Configure the build options of the development board.
You can configure the build options in the **config.gni** file described in step 1. The compilation and building framework will then compile all OS components in the user space based on your configuration. The **config.gni** file contains the following key fields:
```
kernel_type: Kernel used by the development board, for example, LiteOS_A, LiteOS_M, or Linux.
kernel_version: Kernel version used by the development board, for example, 4.19.
board_cpu: CPU of the development board, for example, Cortex-A7 or RISCV32.
board_arch: Chipset architecture of the development board, for example, armv7-a or rv32imac.
board_toolchain: Name of the customized build toolchain used by the development board, for example, gcc-arm-none-eabi. If this field is not specified, ohos-clang will be used.
board_toolchain_prefix: Prefix of the toolchain, for example, gcc-arm-none-eabi.
board_toolchain_type: Toolchain type. Currently, only GCC and clang are supported.
board_cflags: Build options of the .c file configured for the development board.
board_cxx_flags: Build options of the .cpp file configured for the development board.
board_ld_flags: Linking options configured for the development board.
```
For HiSilicon's hispark_taurus development board, the content in **device/hisilicon/hispark_taurus/config.gni** is as follows:
```
# Board CPU type, e.g. "cortex-a7", "riscv32".
board_cpu = "cortex-a7"
# Name of the toolchain used for system building
# E.g. gcc-arm-none-eabi, arm-linux-harmonyeabi-gcc, ohos-clang, riscv32-unknown-elf.
# Note: The "ohos-clang" toolchain is used by default. You can also customize the toolchain.
board_toolchain = "mips-linux-gnu-gcc"
# Path where the toolchain is installed, which can be left blank if the installation path has been added to ~/.bashrc.
# Board storage type, it used for file system generation.
storage_type = "emmc"
```
3. Edit the build script of the development board.
In the **BUILD.gn** file described in step 1, build code related to the development board, such as code for the on-device driver, on-device interface adaptation (media and graphics), and SDK on the development board.
For example, edit the **device/hisilicon/hispark_taurus/BUILD.gn** file as follows:
```
# It is recommended that the group name be the same as the development board name.
...... # Other compilation units of the development board
]
}
```
4. Start building and debugging.
In the directory of the development board, run the **hb set** and **hb build** commands to start building the chipset solution. The compilation and building framework starts the building with the **BUILD.gn** file in the directory as the entry.
> The preceding command is applicable to Ubuntu 18.04. For other Ubuntu versions, modify the preceding installation command based on the installation package name. Specifically:
> The preceding command is applicable to Ubuntu 18.04. For other Ubuntu versions, modify the preceding installation command based on the installation package name. Where:
>
> - Python 3.8 or a later version is required. This section uses Python 3.8 as an example.
>
> - Java 8 or later is required. This section uses Java 8 as an example.
>
> - Java 8 or later is required. This section uses Java 8 as an example.
2. Set Python 3.8 as the default Python version.
Check the location of Python 3.8:
...
...
@@ -52,7 +53,8 @@ On Ubuntu:
To remotely access the Ubuntu environment through Windows to perform operations such as burning, you need to install DevEco Device Tool on both Windows and Ubuntu.
> DevEco Device Tool is a one-stop integrated development environment (IDE) provided for developers of OpenHarmony-powered smart devices. It allows code editing, compiling, burning, and debugging. This document describes how to use DevEco Device Tool to remotely connect to the Ubuntu environment for burning and running.
...
...
@@ -62,11 +64,12 @@ To remotely access the Ubuntu environment through Windows to perform operations
2. Decompress the DevEco Device Tool package, double-click the installer, and then click **Next**.
3. Set the installation path of DevEco Device Tool and click **Next**. You are advised to install DevEco Device Tool in a non-system drive.
3. Set the installation path of DevEco Device Tool to a path that does not contain any Chinese characters, and then click **Next**. You are advised to install DevEco Device Tool in a non-system drive.
> If you have installed DevEco Device Tool 3.0 Beta2 or earlier, the earlier version will be uninstalled before you install a new version. If the following error message is displayed during the uninstallation, click **Ignore** to continue the installation. This error does not affect the installation of the new version.
7. Wait for the DevEco Device Tool setup wizard to automatically install DevEco Device Tool. After the installation is complete, click **Finish** to close the setup wizard.
> If the Ubuntu system has not been set up yet, set it up on a virtual machine running Windows. For details, see [Ubuntu Installation Guide](https://developer.huawei.com/consumer/cn/training/course/video/C101639987816176315). Then, [configure the Ubuntu basic environment](https://developer.huawei.com/consumer/cn/training/course/video/C101639988048536240).
1. Make sure the Ubuntu shell environment is **bash**.
1. Run the following command and check whether the command output is **bash**. If the command output is not **bash**, go to step 2.
```
...
...
@@ -114,6 +125,7 @@ To remotely access the Ubuntu environment through Windows to perform operations
> During the installation, the setup wizard automatically checks whether Python 3.8 or 3.9 is installed. If Python 3.8 or 3.9 is not installed, the setup wizard displays the "Do you want to continue?" message; enter **Y** to allow the setup wizard to automatically install Python.
>
> During the installation, the page for agreeing to the user agreement and privacy statement is displayed. Read and agree to the user agreement and privacy statement.
>
> If this page is not displayed and the installation exits, run the apt-get install whiptail command, then the installation command.
5. On the page for agreeing to the user agreement and privacy statement, read and agree to the user agreement and privacy statement.
Wait until the "Deveco Device Tool successfully installed." message is displayed.
> If the command fails to be executed and the system displays a message indicating that the openssh-server and openssh-client depend on different versions, install the openssh-client of the required version (for example, **sudo apt-get install openssh-client=1:8.2p1-4**) as prompted on the command-line interface (CLI) and run the command again to install the openssh-server.
```
sudo apt-get install openssh-server
```
...
...
@@ -198,10 +211,10 @@ To remotely access the Ubuntu environment through Windows to perform operations
### Remotely Connecting to the Ubuntu Environment
1. Open Visual Studio Code in Windows, click , and click + on the **REMOTE EXOPLORER** page.
2. In the **Enter SSH Connection Command** text box, enter **ssh *username@ip_address***, where *ip_address* indicates the IP address of the remote computer to be connected and *username* indicates the account name used for logging in to the remote computer.
2. In the **Enter SSH Connection Command** text box, enter **ssh *username*\@*ip_address***, where *ip_address* indicates the IP address of the remote computer to be connected and *username* indicates the account name used for logging in to the remote computer.
> To eliminate the need for frequently entering the password for logging in to the remote computer, [set an SSH public key](https://device.harmonyos.com/cn/docs/documentation/guide/ide-registering-public-key-0000001247162706).
After the connection is successful, the plug-in is automatically installed in the .vscode-server folder on the remote computer. After the installation is complete, reload Visual Studio Code in Windows as prompted. Then you can develop, compile, and burn source code in DevEco Device Tool on Windows.
...
...
@@ -256,15 +271,16 @@ In the Ubuntu environment, perform the following steps to obtain the OpenHarmony
```
5. Run the following commands to install the **repo** tool:
In this example, **~/bin** is used as an example installation directory. You can change the directory as needed.
> Download the master code if you want to get quick access to the latest features for your development. Download the release code, which is more stable, if you want to develop commercial functionalities.
For details about the functions of the OpenHarmony compilation and building module, see [Compilation and Building Guidelines](https://gitee.com/openharmony/docs/blob/master/en/device-dev/subsystems/subsys-build.md).
For details about the functions of the OpenHarmony compilation and building module, see [Compilation and Building Guide](../subsystems/subsys-build-all.md).
> _name_ indicates the product name, for example, **hispark_taurus_standard** and **rk3568**.
>
> *name* indicates the product name, for example, **Hi3516DV300** and **rk3568**.
2. Check the build result. After the build is complete, the following information is displayed in the log:
```
...
...
@@ -20,12 +20,13 @@
=====build name successful.
```
Files generated during the build are stored in the **out/{device_name}/** directory, and the generated image is stored in the **out/{device_name}/packages/phone/images/** directory.
> For details about other modular compilation operations, see [Building a Standard System](../subsystems/subsys-build-standard-large.md).
Files generated during the build are stored in the **out/{*device_name*}/** directory, and the generated image is stored in the **out/{*device_name*}/packages/phone/images/** directory.
> The preceding command is applicable to Ubuntu 18.04. For other Ubuntu versions, modify the preceding installation command based on the installation package name. Specifically:
> The preceding command is applicable to Ubuntu 18.04. For other Ubuntu versions, modify the preceding installation command based on the installation package name. Where:
>
> - Python 3.8 or a later version is required. This section uses Python 3.8 as an example.
>
> - Java 8 or later is required. This section uses Java 8 as an example.
>
> - Java 8 or later is required. This section uses Java 8 as an example.
2. Set Python 3.8 as the default Python version.
Check the location of Python 3.8:
...
...
@@ -39,7 +41,7 @@ In Ubuntu:
which python3.8
```
Change python and python3 to python3.8.
Change python and python3 to python3.8.
```
sudo update-alternatives --install /usr/bin/python python {python3.8 path} 1 #{Python3.8 path} is the location of Python 3.8 obtained in the previous step.
...
...
@@ -51,7 +53,8 @@ In Ubuntu:
To remotely access the Ubuntu environment through Windows to perform operations such as burning, you need to install DevEco Device Tool on both Windows and Ubuntu.
> DevEco Device Tool is a one-stop integrated development environment (IDE) provided for developers of OpenHarmony-powered smart devices. It allows code editing, compiling, burning, and debugging. This document describes how to use DevEco Device Tool to remotely connect to the Ubuntu environment for burning and running.
...
...
@@ -61,8 +64,10 @@ To remotely access the Ubuntu environment through Windows to perform operations
2. Decompress the DevEco Device Tool package, double-click the installer, and then click **Next**.
3. Set the installation path of DevEco Device Tool and click **Next**. You are advised to install DevEco Device Tool in a non-system drive.
3. Set the installation path of DevEco Device Tool to a path that does not contain any Chinese characters, and then click **Next**. You are advised to install DevEco Device Tool in a non-system drive.
> If you have installed DevEco Device Tool 3.0 Beta2 or earlier, the earlier version will be uninstalled before you install a new version. If the following error message is displayed during the uninstallation, click **Ignore** to continue the installation. This error does not affect the installation of the new version.
> If the Ubuntu system has not been set up yet, set it up on a virtual machine running Windows. For details, see [Ubuntu Installation Guide](https://developer.huawei.com/consumer/cn/training/course/video/C101639987816176315). Then, [configure the Ubuntu basic environment](https://developer.huawei.com/consumer/cn/training/course/video/C101639988048536240).
1. Make sure the Ubuntu shell environment is **bash**.
1. Run the following command and check whether the command output is **bash**. If the command output is not **bash**, go to step 2.
```
...
...
@@ -108,6 +126,7 @@ To remotely access the Ubuntu environment through Windows to perform operations
2. Download the [DevEco Device Tool 3.0 Release Linux version](https://device.harmonyos.com/cn/ide#download).
2. Download the [DevEco Device Tool 3.0 Release](https://device.harmonyos.com/cn/ide#download) Linux edition.
3. Decompress the DevEco Device Tool software package and assign permission on the folder obtained from the decompression.
1. Go to the directory where the DevEco Device Tool software package is stored and run the following command to decompress the software package. In the command, change **devicetool-linux-tool-3.0.0.401.zip** to the actual software package name.
```
...
...
@@ -135,25 +155,25 @@ To remotely access the Ubuntu environment through Windows to perform operations
> During the installation, the setup wizard automatically checks whether Python 3.8 or 3.9 is installed. If Python 3.8 or 3.9 is not installed, the setup wizard displays the "Do you want to continue?" message; enter **Y** to allow the setup wizard to automatically install Python.
>
> During the installation, the page for agreeing to the user agreement and privacy statement is displayed. Read and agree to the user agreement and privacy statement.
>
> If this page is not displayed and the installation exits, run the apt-get install whiptail command, then the installation command.
Wait until the "Deveco Device Tool successfully installed." message is displayed.
5. On the page for agreeing to the user agreement and privacy statement, read and agree to the user agreement and privacy statement.
> If the command fails to be executed and the system displays a message indicating that the openssh-server and openssh-client depend on different versions, install the openssh-client of the required version (for example, **sudo apt-get install openssh-client=1:8.2p1-4**) as prompted on the command-line interface (CLI) and run the command again to install the openssh-server.
...
...
@@ -193,7 +213,7 @@ To remotely access the Ubuntu environment through Windows to perform operations
2. In the **Enter SSH Connection Command** text box, enter **ssh *ssh _username_\@_ip_address_***, where *ip_address* indicates the IP address of the remote computer to be connected and *username* indicates the account name used for logging in to the remote computer.
2. In the **Enter SSH Connection Command** text box, enter **ssh *username*\@*ip_address***, where *ip_address* indicates the IP address of the remote computer to be connected and *username* indicates the account name used for logging in to the remote computer.
> To eliminate the need for frequently entering the password for logging in to the remote computer, set an SSH public key.
>
> To eliminate the need for frequently entering the password for logging in to the remote computer, [set an SSH public key](https://device.harmonyos.com/cn/docs/documentation/guide/ide-registering-public-key-0000001247162706).
After the connection is successful, the plug-in is automatically installed in the .vscode-server folder on the remote computer. After the installation is complete, reload Visual Studio Code in Windows as prompted. Then you can develop, compile, and burn source code in DevEco Device Tool on Windows.
...
...
@@ -228,7 +250,7 @@ In the Ubuntu environment, perform the following steps to obtain the OpenHarmony
3. Install the git client and git-lfs. (Skip this step if these tools have been installed in Installing Required Libraries and Tools. )
Update the software source:
```
sudo apt-get update
```
...
...
@@ -248,15 +270,16 @@ In the Ubuntu environment, perform the following steps to obtain the OpenHarmony
```
5. Run the following commands to install the **repo** tool:
In this example, **~/bin** is used as an example installation directory. You can change the directory as needed.
> Download the master code if you want to get quick access to the latest features for your development. Download the release code, which is more stable, if you want to develop commercial functionalities.
-**Obtaining OpenHarmony master code**
Method 1 \(recommended\): Use the **repo** tool to download the source code over SSH. \(You must have registered an SSH public key for access to Gitee.\)
@@ -296,20 +321,21 @@ In the Ubuntu environment, perform the following steps to obtain the OpenHarmony
### Running prebuilts
Go to the root directory of the source code and run the following script to install the compiler and binary tool:
Go to the root directory of the source code and run the following script to install the compiler and binary tool:
```
bash build/prebuilts_download.sh
```
## Installing the Compilation Tool
## Installing the Compilation Tools
hb is a compilation tool of OpenHarmony. To install hb in Ubuntu, perform the following steps: For details about the functions of the OpenHarmony compilation and building module, see [Compilation and Building Guidelines](https://gitee.com/openharmony/docs/blob/master/en/device-dev/subsystems/subsys-build.md).
hb is a compilation tool of OpenHarmony. To install hb in Ubuntu, perform the following steps. For details about the functions of the OpenHarmony compilation and building module, see [Compilation and Building Guide](../subsystems/subsys-build-all.md).
> _name_ indicates the product name, for example, **hispark_taurus_standard** and **rk3568**.
>
> *name* indicates the product name, for example, **Hi3516DV300** and **rk3568**.
2. Check the build result. After the build is complete, the following information is displayed in the log:
```
...
...
@@ -20,9 +20,10 @@
=====build name successful.
```
Files generated during the build are stored in the **out/{device_name}/** directory, and the generated image is stored in the **out/{device_name}/packages/phone/images/** directory.
Files generated during the build are stored in the **out/{*device_name*}/** directory, and the generated image is stored in the **out/{*device_name*}/packages/phone/images/** directory.
