1# Building Guidelines for Standard Systems<a name="EN-US_TOPIC_0000001076490572"></a> 2 3- [Overview](#section17466112012244) 4 - [Basic Concepts](#section445513507246) 5 - [Working Principles](#section12541217142510) 6 - [Limitations and Constraints](#section886933762513) 7 8- [Compilation and Building Guidelines](#section16901215262) 9 - [Directory Structure](#section109065332264) 10 - [Build Command](#section123265539266) 11 - [How to Develop](#section591084422719) 12 13 14## Overview<a name="section17466112012244"></a> 15 16The compilation and building subsystem provides a framework based on Generate Ninja \(GN\) and Ninja. This subsystem allows you to: 17 18- Build products based on different chipset platforms, for example, Hi3516D V300. 19 20- Package capabilities required by a product by assembling modules based on the product configuration. 21 22### Basic Concepts<a name="section445513507246"></a> 23 24It is considered best practice to learn the following basic concepts before you start building: 25 26- **Platform** 27 28 A platform is a combination of development boards and kernels. 29 30 Supported subsystems and modules vary according to the platform. 31 32- **Subsystems** 33 34 OpenHarmony is designed with a layered architecture, which from bottom to top consists of the kernel layer, system service layer, framework layer, and application layer. System functions are expanded by levels, from system to subsystem, and further to module. In a multi-device deployment scenario, unnecessary subsystems and modules can be excluded from the system as required. A subsystem is a logical concept and is a flexible combination of functions. 35 36- **Module** 37 38 A module is a reusable software binary unit that contains source code, configuration files, resource files, and build scripts. A module can be built independently, integrated in binary mode, and then tested independently. 39 40- **GN** 41 42 GN is short for Generate Ninja, which is used to generate Ninja files. 43 44- **Ninja** 45 46 Ninja is a small high-speed build system. 47 48 49### Working Principles<a name="section12541217142510"></a> 50 51The process to build OpenHarmony is as follows: 52 53- Parsing commands: Parse the name of the product to build and load related configurations. 54- Running GN: Configure toolchains and global options based on the parsed product name and compilation type. 55- Running Ninja: Start building and generate a product distribution. 56 57### Limitations and Constraints<a name="section886933762513"></a> 58 59- You must download the source code using method 3 described in [Source Code Acquisition](../get-code/sourcecode-acquire.md). 60- The build environment must be Ubuntu 18.04 or later. 61- You must install the software package required for build. 62 63 The installation command is as follows: 64 65 ``` 66 sudo apt-get install binutils git-core gnupg flex bison gperf build-essential zip curl zlib1g-dev gcc-multilib g++-multilib libc6-dev-i386 lib32ncurses5-dev x11proto-core-dev libx11-dev lib32z-dev ccache libgl1-mesa-dev libxml2-utils xsltproc unzip m4 67 ``` 68 69 70## Compilation and Building Guidelines<a name="section16901215262"></a> 71 72### Directory Structure<a name="section109065332264"></a> 73 74``` 75/build # Primary directory 76├── config # Build configuration items 77├── core 78│ └── gn # Build entry BUILD.gn configuration 79├── loader # Loader of module configuration, which also generates a template for the module 80├── ohos # Configuration of the process for building and packaging OpenHarmony 81│ ├── kits # Build and packaging templates and processing flow for kits 82│ ├── ndk # NDK template and processing flow 83│ ├── notice # Notice template and processing flow 84│ ├── packages # Distribution packaging template and processing flow 85│ ├── sa_profile # SA template and processing flow 86│ ├── sdk # SDK template and processing flow, which contains the module configuration in the SDK 87│ └── testfwk # Processing flow related to the test 88├── scripts # Build-related Python script 89├── templates # C/C++ build templates 90└── toolchain # Toolchain configuration 91``` 92 93### Build Command<a name="section123265539266"></a> 94 95- Run the following command in the root directory of the source code to build the full distribution: 96 97 ``` 98 ./build.sh --product-name {product_name} 99 ``` 100 101 **product\_name** indicates the product supported by the current distribution, for example, Hi3516D V300. 102 103 The image generated after build is stored in the **out/ohos-arm-release/packages/phone/images/** directory. 104 105- The build command supports the following options: 106 107 ``` 108 --product-name # (Mandatory) Name of the product to build, for example, Hi3516D V300 109 --build-target # (Optional) One or more build targets 110 --gn-args # (Optional) One or more gn parameters 111 --ccache # (Optional) Use of Ccache for build. This option takes effect only when Ccache is installed on the local PC. 112 ``` 113 114 115### How to Develop<a name="section591084422719"></a> 116 1171. Add a module. 118 119 The following steps use a custom module as an example to describe how to build the module, including build a library, an executable file, and a configuration file. 120 121 The example module **partA** consists of **feature1**, **feature2**, and **feature3**. The target is a dynamic library for **feature1**, an executable file for **feature2**, and an etc configuration file for **feature3**. 122 123 Add **partA** to a subsystem, for example, **subsystem\_examples** \(defined in the **test/examples/** directory\). 124 125 The complete directory structure of **partA** is as follows: 126 127 ``` 128 test/examples/partA 129 ├── feature1 130 │ ├── BUILD.gn 131 │ ├── include 132 │ │ └── helloworld1.h 133 │ └── src 134 │ └── helloworld1.cpp 135 ├── feature2 136 │ ├── BUILD.gn 137 │ ├── include 138 │ │ └── helloworld2.h 139 │ └── src 140 │ └── helloworld2.cpp 141 └── feature3 142 ├── BUILD.gn 143 └── src 144 └── config.conf 145 ``` 146 147 Example 1: GN script \(**test/examples/partA/feature1/BUILD.gn**\) for building a dynamic library 148 149 ``` 150 config("helloworld_lib_config") { 151 include_dirs = [ "include" ] 152 } 153 154 ohos_shared_library("helloworld_lib") { 155 sources = [ 156 "include/helloworld1.h", 157 "src/helloworld1.cpp", 158 ] 159 public_configs = [ ":helloworld_lib_config" ] 160 part_name = "partA" 161 } 162 ``` 163 164 Example 2: GN script \(**test/examples/partA/feature2/BUILD.gn**\) for building an executable file 165 166 ``` 167 ohos_executable("helloworld_bin") { 168 sources = [ 169 "src/helloworld2.cpp" 170 ] 171 include_dirs = [ "include" ] 172 deps = [ # Dependent submodule 173 "../feature1:helloworld_lib" 174 ] 175 external_deps = [ "partB:module1" ] # (Optional) If there is a cross-module dependency, the format is "module name: submodule name" 176 install_enable = true # By default, the executable file is not installed. You need to set this parameter to true for installation. 177 part_name = "partA" 178 } 179 ``` 180 181 Example 3: GN script \(**test/examples/partA/feature3/BUILD.gn**\) for building the etc configuration file \(submodule\). 182 183 ``` 184 ohos_prebuilt_etc("feature3_etc") { 185 source = "src/config.conf" 186 relative_install_dir = "init" # (Optional) Directory for installing the submodule, which is relative to the default installation directory (/system/etc) 187 part_name = "partA" 188 } 189 ``` 190 191 Example 4: Adding the module configuration file **test/examples/ohos.build** to the **ohos.build** file of this subsystem. Each subsystem has an **ohos.build** file in its root directory. Example: 192 193 ``` 194 "partA": { 195 "module_list": [ 196 "//test/examples/partA/feature1:helloworld_lib", 197 "//test/examples/partA/feature2:helloworld_bin", 198 "//test/examples/partA/feature3:feature3_etc", 199 ], 200 "inner_kits": [ 201 202 ], 203 "system_kits": [ 204 205 ], 206 "test_list": [ 207 208 ] 209 } 210 ``` 211 212 The declaration of a module contains the following parts: 213 214 - **module\_list**: submodule list of the module 215 - **inner\_kits**: APIs for other modules that depend on this module through **external\_deps** 216 - **system\_kits**: APIs for developers 217 - **test\_list**: test cases for the submodules of the module 218 2192. Add the module to the product configuration file. 220 221 Add the module to the product configuration file **productdefine/common/products/\{product-name\}.json**. 222 223 Add "subsystem\_examples:partA" to the product configuration file. **partA** will be built and packaged into the distribution. 224 2253. Build the module. 226 227 For example, run the following command to build Hi3516D V300: 228 229 ``` 230 ./build.sh --product-name Hi3516DV300 --ccache 231 ``` 232 2334. Obtain the build result. 234 235 Files generated during the build process are stored in the **out/ohos-arm-release/** directory, and the generated image is stored in the **out/ohos-arm-release/packages/phone/images/** directory. 236 237 238