Skip to content

D
Docs

OpenHarmony / Docs
大约 1 年 前同步成功

通知 159
Star 292
Fork 28
D
Docs

体验新版 GitCode，发现更多精彩内容 >>

提交 85752d43 编写于 作者: A Annie_wang
浏览文件
操作

update docs 

Signed-off-by: NAnnie_wang <annie.wangli@huawei.com>
上级 a2cecc46
隐藏空白更改
内联 并排
Showing with 160 addition and 126 deletion
en/device-dev/subsystems/subsys-build-module.md
浏览文件 @ 85752d43
# Module
## Configuration Rules
The Compilation and Building subsystem implements compilation and packaging by module, component, and product. A module is an 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 uses customized GN templates to configure modules. For details about the GN basics, see https://gn.googlesource.com/gn/+/main/docs/reference.md.
The 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).
The common templates for module configuration are as follows:
......@@ -25,15 +25,15 @@ ohos_resources
# Other templates
# Configuration file
ohos_prebuild_etc
ohos_prebuilt_etc
# SA profile
ohos_sa_profile
```
You are recommended to use the OpenHarmony customized templates.
You are advised to use the OpenHarmony customized templates.
### C/C++ Template Example
### C/C++ Template Examples
The .gni file corresponding to the templates starting with **ohos** is located in **openharmony/build/templates/cxx/cxx.gni**.
......@@ -62,19 +62,25 @@ ohos_shared_library("helloworld") {
part_name = [string] # (Mandatory) Component name.
output_dir
# Sanitizer variables
cfi = [boolean]
cfi_cross_dso = [boolean] # CFI: shared library support.
scs = [boolean]
scudo = []
ubsan = []
boundary_sanitize = []
integer_overflow_sanitize = []
# Sanitizer configuration. Each item is optional, and set to false or left unspecified by default.
sanitize = {
# Sanitizer settings
cfi = [boolean] # Whether to enable the control-flow integrity (CFI) check.
cfi_cross_dso = [boolean] # Whether to enable the cross-DSO CFI check.
integer_overflow = [boolean] # Whether to enable the integer overflow check.
boundary_sanitize = [boolean] # Whether to enable the bounds check.
ubsan = [boolean] # Whether to enable some Undefined Behavior Sanitizer (UBSAN) options.
all_ubsan = [boolean] # Whether to enable all UBSAN options.
...
debug = [boolean] # Whether to enable the debug mode.
blocklist = [string] # Path of the blocklist.
}
testonly = [boolean]
license_as_sources = []
license_file = [] # A .txt file.
license_file = [] # A .txt file.
remove_configs = []
no_default_deps = []
install_images = []
......@@ -104,19 +110,25 @@ ohos_static_library("helloworld") {
lib_dirs = []
public_configs = []
# Sanitizer variables
cfi = [boolean]
cfi_cross_dso = [boolean] # CFI: shared library support.
scs = [boolean]
scudo = []
ubsan = []
boundary_sanitize = []
integer_overflow_sanitize = []
# Sanitizer configuration. Each item is optional, and set to false or left unspecified by default.
sanitize = {
# Sanitizer settings
cfi = [boolean] # Whether to enable the CFI check.
cfi_cross_dso = [boolean] # Whether to enable the cross-DSO CFI check.
integer_overflow = [boolean] # Whether to enable the integer overflow check.
boundary_sanitize = [boolean] # Whether to enable the bounds check.
ubsan = [boolean] # Whether to enable some UBSAN options.
all_ubsan = [boolean] # Whether to enable all UBSAN options.
...
debug = [boolean] # Whether to enable the debug mode.
blocklist = [string] # Path of the blocklist.
}
remove_configs = []
no_default_deps = []
license_file = [] # A .txt file.
license_file = [] # A .txt file.
license_as_sources = []
use_exceptions = []
}
......@@ -137,26 +149,32 @@ ohos_executable("helloworld") {
] # The dependent modules must be declared in inner_kits by the dependent component.
ohos_test = []
test_output_dir = []
# Sanitizer variables
cfi = [boolean]
cfi_cross_dso = [boolean] # CFI: shared library support.
scs = [boolean]
scudo = []
ubsan = []
boundary_sanitize = []
integer_overflow_sanitize = []
# Sanitizer configuration. Each item is optional, and set to false or left unspecified by default.
sanitize = {
# Sanitizer settings
cfi = [boolean] # Whether to enable the CFI check.
cfi_cross_dso = [boolean] # Whether to enable the cross-DSO CFI check.
integer_overflow = [boolean] # Whether to enable the integer overflow check.
boundary_sanitize = [boolean] # Whether to enable the bounds check.
ubsan = [boolean] # Whether to enable some Undefined Behavior Sanitizer (UBSAN) options.
all_ubsan = [boolean] # Whether to enable all UBSAN options.
...
debug = [boolean] # Whether to enable the debug mode.
blocklist = [string] # Path of the blocklist.
}
testonly = [boolean]
license_as_sources = []
license_file = [] # A .txt file.
license_file = [] # A .txt file.
remove_configs = []
static_link = []
install_images = []
module_install_dir = [] # Module installation directory, starting from system/ or vendor/.
module_install_dir = [] # Module installation directory, starting from system/ or vendor/.
relative_install_dir = []
symlink_target_name = []
output_dir = [directory] # Directory in which output files are located.
output_dir = [directory] # Directory in which output files are located.
install_enable = [boolean]
version_script = []
use_exceptions = []
......@@ -168,43 +186,52 @@ ohos_executable("helloworld") {
```shell
import("//build/ohos.gni")
ohos_source_set("helloworld") {
sources = ["file"] # Source code in .c format.
include_dirs = [] # Directories to be included.
configs = [] # Configuration.
public = [] # Header files.
sources = ["file"] # Source code in .c format.
include_dirs = [] # Directories to be included.
configs = [] # Configuration.
public = [] # Header files.
defines = []
public_configs = []
part_name = [string] # Component name.
subsystem_name = [string] # Subsystem name.
part_name = [string] # Component name.
subsystem_name = [string] # Subsystem name.
deps = [] # Define dependent modules that belong to the same component.
external_deps = [ # Define dependent modules that belong to different components.
"part_name:module_name", # The value is in the Component_name:Module_name format.
] # The dependent modules must be declared in inner_kits by the dependent component.
# Sanitizer variables
cfi = [boolean]
cfi_cross_dso = [boolean] # CFI: shared library support.
scs = [boolean]
scudo = []
ubsan = []
boundary_sanitize = []
integer_overflow_sanitize = []
external_deps = [ # Define dependent modules that belong to different components.
"part_name:module_name", # The value is in the Component_name:Module_name format.
] # The dependent modules must be declared in inner_kits by the dependent component.
# Sanitizer configuration. Each item is optional, and set to false or left unspecified by default.
sanitize = {
# Sanitizer settings
cfi = [boolean] # Whether to enable the CFI check.
cfi_cross_dso = [boolean] # Whether to enable the cross-DSO CFI check.
integer_overflow = [boolean] # Whether to enable the integer overflow check.
boundary_sanitize = [boolean] # Whether to enable the bounds check.
ubsan = [boolean] # Whether to enable some Undefined Behavior Sanitizer (UBSAN) options.
all_ubsan = [boolean] # Whether to enable all UBSAN options.
...
debug = [boolean] # Whether to enable the debug mode.
blocklist = [string] # Path of the blocklist.
}
testonly = [boolean]
license_as_sources = []
license_file = []
remove_configs = []
no_default_deps = []
license_file = [] # A .txt file.
license_file = [] # A .txt file.
license_as_sources = []
use_exceptions = []
}
```
>**NOTE**<br>Only **sources** and **part_name** are mandatory.
> **NOTE**
>
> - Only **sources** and **part_name** are mandatory.
> - For details about the Sanitizer configuration, see [Using Sanitizer](subsys-build-reference.md#using-sanitizer).
### Prebuilt Template Example
### Prebuilt Template Examples
The .gni file of the prebuilt templates is located in **openharmony/build/templates/cxx/prebuilt.gni**.
......@@ -213,25 +240,25 @@ The .gni file of the prebuilt templates is located in **openharmony/build/templa
```shell
import("//build/ohos.gni")
ohos_prebuilt_executable("helloworld") {
sources = ["file"] # Source.
sources = ["file"] # Source.
output = []
install_enable = [boolean]
deps = [] # Define dependent modules that belong to the same component.
deps = [] # Define dependent modules that belong to the same component.
public_configs = []
subsystem_name = [string] # Subsystem name.
part_name = [string] # Component name.
subsystem_name = [string] # Subsystem name.
part_name = [string] # Component name.
testonly = [boolean]
visibility = []
install_images = []
module_install_dir = [] # Module installation directory, starting from system/ or vendor/.
relative_install_dir = [] # Relative module installation directory (relative to system/etc). If module_install_dir is configured, the parameter does not take effect.
module_install_dir = [] # Module installation directory, starting from system/ or vendor/.
relative_install_dir = [] # Relative module installation directory (relative to system/etc). If module_install_dir is configured, the parameter does not take effect.
symlink_target_name = []
license_file = [] # A .txt file.
license_file = [] # A .txt file.
license_as_sources = []
}
```
......@@ -241,25 +268,25 @@ ohos_prebuilt_executable("helloworld") {
```shell
import("//build/ohos.gni")
ohos_prebuilt_shared_library("helloworld") {
sources = ["file"] # .so files.
sources = ["file"] # .so files.
output = []
install_enable = [boolean]
deps = [] # Define dependent modules that belong to the same component.
deps = [] # Define dependent modules that belong to the same component.
public_configs = []
subsystem_name = [string] # Subsystem name.
part_name = [string] # Component name.
subsystem_name = [string] # Subsystem name.
part_name = [string] # Component name.
testonly = [boolean]
visibility = []
install_images = []
module_install_dir = [] # Module installation directory, starting from system/ or vendor/.
relative_install_dir = [] # Relative module installation directory (relative to system/etc). If module_install_dir is configured, the parameter does not take effect.
module_install_dir = [] # Module installation directory, starting from system/ or vendor/.
relative_install_dir = [] # Relative module installation directory (relative to system/etc). If module_install_dir is configured, the parameter does not take effect.
symlink_target_name = [string]
license_file = [string] # A .txt file.
license_file = [string] # A .txt file.
license_as_sources = []
}
```
......@@ -289,7 +316,7 @@ ohos_prebuilt_static_library("helloworld") {
### HAP Templates
See [HAP Build Guide](subsys-build-gn-hap-compilation-guide.md).
For details, see [HAP Build Guide](subsys-build-gn-hap-compilation-guide.md).
......@@ -330,11 +357,11 @@ ohos_sa_profile("helloworld") {
}
```
>**NOTE**: Only **sources** and **part_name** are mandatory.
> **NOTE**<br>Only **sources** and **part_name** are mandatory.
## Adding and Building a Module
The figure below illustrates the process for adding a module. A module belongs to a component, which belongs to a subsystem. Please note that the chipset solution, as a special component, does not have a subsystem. You may need to:
The 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.
- Add a module to an existing component.
......@@ -352,47 +379,47 @@ The figure below illustrates the process for adding a module. A module belongs t
```shell
{
"name": "@ohos/<component_name>, # HPM component name, in the "@Organization/Component_name" format.
"description": "xxxxxxxxxxxxxxxxxxx", # Description of the component functions.
"version": "3.1", # Version, which must be the same as the version of OpenHarmony.
"license": "MIT", # Component license.
"publishAs": "code-segment", # HPM package release mode. The default value is code-segment.
"name": "@ohos/<component_name>, # HPM component name, in the "@Organization/Component_name" format.
"description": "xxxxxxxxxxxxxxxxxxx", # Description of the component functions.
"version": "3.1", # Version, which must be the same as the version of OpenHarmony.
"license": "MIT", # Component license.
"publishAs": "code-segment", # HPM package release mode. The default value is code-segment.
"segment": {
"destPath": "third_party/nghttp2"
}, # Code restoration path (source code path) set when publishAs is code-segment.
"dirs": {}, # Directory structure of the HPM package. This field is mandatory and can be left empty.
"scripts": {}, # Scripts to be executed. This field is mandatory and can be left empty.
}, # Code restoration path (source code path) set when publishAs is code-segment.
"dirs": {}, # Directory structure of the HPM package. This field is mandatory and can be left empty.
"scripts": {}, # Scripts to be executed. This field is mandatory and can be left empty.
"licensePath": "COPYING",
"readmePath": {
"en": "README.rst"
},
"component": { # Component attributes.
"name": "<component_name>", # Component name.
"subsystem": "", # Subsystem to which the component belongs.
"syscap": [], # System capabilities provided by the component for applications.
"features": [], # List of configurable features of the component. Generally, this parameter corresponds to sub_component in build.
"adapted_system_type": [], # Types of adapted systems. The value can be mini, small, standard, or their combinations.
"rom": "xxxKB" # ROM baseline. If there is no baseline, enter the current value.
"ram": "xxxKB", # RAM baseline. If there is no baseline, enter the current value.
"component": { # Component attributes.
"name": "<component_name>", # Component name.
"subsystem": "", # Subsystem to which the component belongs.
"syscap": [], # System capabilities provided by the component for applications.
"features": [], # List of configurable features of the component. Generally, this parameter corresponds to sub_component in build.
"adapted_system_type": [], # Types of adapted systems. The value can be mini, small, standard, or their combinations.
"rom": "xxxKB" # ROM baseline. If there is no baseline, enter the current value.
"ram": "xxxKB", # RAM baseline. If there is no baseline, enter the current value.
"deps": {
"components": [ # Other components on which this component depends.
"third_party": [ # Third-party open-source software on which this component depends.
"components": [ # Other components on which this component depends.
"third_party": [ # Third-party open-source software on which this component depends.
},
"build": { # Build-related configuration.
"build": { # Build-related configuration.
"sub_component": [
"//foundation/arkui/napi:napi_packages", # Existing module 1.
"//foundation/arkui/napi:napi_packages_ndk" # Existing module 2.
"//foundation/arkui/napi:new" # Module to add.
], # Component build entry. Configure the module here.
"inner_kits": [], # APIs between components.
"test": [] # Entry for building the component's test cases.
"//foundation/arkui/napi:napi_packages", # Existing module 1.
"//foundation/arkui/napi:napi_packages_ndk"# Existing module 2.
"//foundation/arkui/napi:new" # Module to add.
], # Component build entry. Configure the module here.
"inner_kits": [], # APIs between components.
"test": [] # Entry for building the component's test cases.
}
}
}
```
>**NOTE**<br>The **bundle.json** file must be in the folder of the corresponding subsystem.
> **NOTE**<br>The **bundle.json** file must be in the folder of the corresponding subsystem.
3. Start the build and check whether a .so file or binary file is generated.
......@@ -471,7 +498,7 @@ The figure below illustrates the process for adding a module. A module belongs t
]
},
{
"subsystem": "subsystem_new", # Name of the new subsystem to add
"subsystem": "subsystem_new", # Name of the new subsystem to add.
"components": [
{
"component": "component_new2", # Name of the component to be added to the new subsystem
......@@ -485,25 +512,25 @@ The figure below illustrates the process for adding a module. A module belongs t
4. Start the build and check whether a .so file or binary file is generated.
**Building a Module**
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:
You can run the **--build-target** *Module_name* command to build a module separately.
```shell
./build.sh --build-target Module_name
```
```shell
./build.sh --build-target Module_name
```
You can also build a product. For example, to build hispark_taurus_standard, run the following command:
```shell
./build.sh --product-name hispark_taurus_standard --build-target Module_name --ccache
```
```shell
./build.sh --product-name hispark_taurus_standard --build-target Module_name --ccache
```
You can also build the component to which the module belongs.
```shell
./build.sh --product-name hispark_taurus_standard --build-target musl --build-target Module_name --ccache
```
```shell
./build.sh --product-name hispark_taurus_standard --build-target musl --build-target Module_name --ccache
```
en/device-dev/subsystems/subsys-build-reference.md
浏览文件 @ 85752d43
......@@ -55,8 +55,8 @@ The dependency between modules can be classified into **deps** (left in the figu
external_deps = [
"part1:module1",
...
] # Inter-component dependency. The dependent module must be declared in inner_kits by the dependent component.
part_name = "part2" # (Mandatory) Name of the component to which the module belongs.
] # Inter-component dependency. The dependent module must be declared in inner_kits by the dependent component.
part_name = "part2" # (Mandatory) Name of the component to which the module belongs.
}
```
......@@ -64,18 +64,21 @@ The dependency between modules can be classified into **deps** (left in the figu
## Using Sanitizer
When 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. It is **false** by default. You can also leave it empty.
When 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.
Sanitizer configuration example:
``` shell
ohos_shared_library("example") {
sanitize = {
cfi = true
cfi_cross_dso = true # CFI: shared library support.
integer_overflow = true
debug = true # Optional. The debug mode is disabled by default.
blocklist = "./blocklist.txt" # Optional. Enter the path of the blocklist.
cfi = true # Enable the CFI check.
cfi_cross_dso = true # Enable the cross-DSO CFI check.
integer_overflow = true # Enable the integer overflow check.
boundary_sanitize = true # Enable the bounds check.
ubsan = true # Enable some UBSAN options.
all_ubsan = true # Enable all UBSAN options.
debug = true # Enable the debug mode, which is disabled by default.
blocklist = "./blocklist.txt" # Path of the blocklist.
}
...
}
......@@ -83,10 +86,13 @@ Sanitizer configuration example:
**Supported Sanitizer Types**
Currently, the following two types of Sanitizers are supported:
Currently, Sanitizers provides the following functions:
- Integer overflow check: provides check of unsigned integer overflow (unsigned_integer_overflow), check of signed integer overflow (signed_integer_overflow), or both (integer_overflow).
- CFI: prevents malware attacks from redirecting the control flow of a program.
- **integer_overflow**: provides check of unsigned integer overflow (unsigned_integer_overflow), check of signed integer overflow (signed_integer_overflow), or both (integer_overflow).
- CFI: provides CFI and cross-DSO CFI checks.
- **boundary_sanitize**: provides the bounds check.
- **ubsan**: checks some Undefined Behavior Sanitizer (UBSAN) options, including **bool**, **integer-divide-by-zero**, **return**, **returns-nonnull-attribute**, **shift-exponent**, **unreachable**, and **vla-bound**.
- **all_ubsan**: checks all UBSAN options.
**Release and Debug Modes**
......@@ -96,6 +102,7 @@ Currently, the following two types of Sanitizers are supported:
- 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.
**Blocklist**
The 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.
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或