diff --git a/zh-cn/device-dev/subsystems/Readme-CN.md b/zh-cn/device-dev/subsystems/Readme-CN.md index e500ccff34ca0cbceb289669343126349cd5e9af..a6c63fb464bce5a46ae3a9c4ca57cda1c7bf18b3 100644 --- a/zh-cn/device-dev/subsystems/Readme-CN.md +++ b/zh-cn/device-dev/subsystems/Readme-CN.md @@ -8,7 +8,7 @@ - [产品配置规则](subsys-build-product.md#产品配置规则) - [子系统配置规则](subsys-build-subsystem.md#子系统配置规则) - [部件配置规则](subsys-build-component.md#部件配置规则) - - [OpenHarmony部件编译构建规范](subsys-build-component-building-rules.md#OpenHarmony部件编译构建规范) + - [部件编译构建规范](subsys-build-component-building-rules.md#OpenHarmony部件编译构建规范) - [模块配置规则](subsys-build-module.md#模块配置规则) - [芯片解决方案配置规则](subsys-build-chip_solution.md#芯片解决方案配置规则) - [特性配置规则](subsys-build-feature.md#特性配置规则) diff --git a/zh-cn/device-dev/subsystems/subsys-build-component-building-rules.md b/zh-cn/device-dev/subsystems/subsys-build-component-building-rules.md index 61d21e4eda1636e780f4d023145692ddc9037934..dffb40dde7b69e1f4c9938958c454d450a7fbab2 100644 --- a/zh-cn/device-dev/subsystems/subsys-build-component-building-rules.md +++ b/zh-cn/device-dev/subsystems/subsys-build-component-building-rules.md @@ -1,4 +1,4 @@ -# OpenHarmony部件编译构建规范 +# 部件编译构建规范 ## 0 前言 @@ -10,18 +10,18 @@ **部件** -部件是OpenHarmony系统能力的基本单元 ，以源码为划分依据，具有独立的仓和目录 ，在不同的设备上可实例化为不同的库或二进制文件。 +部件是OpenHarmony系统能力的基本单元，以源码为划分依据，具有独立的仓和目录，在不同的设备上可实例化为不同的库或二进制文件。 **特性** -部件特性为编译态可配置的编译选项，可供产品在编译按需配置。不同的特性配置，编译出部件的不同形态，使得部件可以适应不同形态产品的差异化需求。部件特性的配置只影响部件内部功能的实现差异，不能影响部件的 Public API（部件对应用提供的接口）以及 inner api（部件间的接口） 。 +部件特性为编译态可配置的编译选项，可供产品在编译时按需配置。不同的特性配置，编译出部件的不同形态，使得部件可以适应不同形态产品的差异化需求。部件特性的配置只影响部件内部功能的实现差异，不能影响部件的Public API（部件对应用提供的接口）以及inner api（部件间的接口）。 **依赖** 在编译态，部件的依赖分为： -- 有条件依赖：在特定场景下可裁剪的依赖，有条件的依赖裁剪后不影响部件的 Public API 和 inner api。比如音频对蓝牙的依赖。 -- 强依赖：部件间合理的必要的依赖，不可裁剪。比如对安全库函数的依赖。 +- 有条件依赖：在特定场景下可裁剪的依赖，有条件的依赖裁剪后不影响部件的Public API 和inner api。比如音频对蓝牙的依赖。 +- 强依赖：部件间合理的必要的依赖，不可裁剪。比如syscap部件对安全库函数的依赖。 ### 总体原则 @@ -43,18 +43,18 @@ **建议：** 必须加以考虑的约定。 -无论是“规则”还是“建议”，都必须并努力遵守。 ### 例外 在不违背总体原则，经过充分考虑，有充足的理由的前提下，可以适当违背规范中约定。 + 例外破坏了代码的一致性，请尽量避免。“规则”的例外应该是极少的。 ## 1 命名 编译脚本中的变量、编译目标（target）、模板，gni文件，以及部件描述文件中的对象和数据的命名都应采用内核风格（unix_like），单词全小写，用下划线分割。如："startup_init"。 -### 规则1.1 部件英文名格式须统一 +### 规则1.1 部件名格式须统一 - 名词形式，需体现部件的功能。 - 在系统内全局唯一。 - 不超过63个有效英文字符。 @@ -73,7 +73,7 @@ declare_args() { } ``` -**看护手段：** 预编译检查 +看护手段：预编译检查 ### 建议1.1 编译目标名以部件名为前缀加上模块名称 @@ -90,28 +90,28 @@ ohos_shared_library("cellular_data_napi") // Good ## 2 描述文件 -bundle.json 是定义部件的描述文件，包含了部件的根目录、名称、功能描述、版本号、接口定义和编译入口等信息，须保证其准确性。 +bundle.json是定义部件的描述文件，包含了部件的根目录、名称、功能描述、版本号、接口定义和编译入口等信息，须保证其准确性。 ### 规则2.1 部件描述文件中字段须准确 | 字段 | 类型 | 看护手段 | |---|---|---| -|name|string。部件的HPM（鸿蒙包管理器）包名称，必填。命名规则：@{organization}/{component_name}。"component_name" 为部件的名称，须满足规则1.1。|静态检查| -|version|string。部件版本号，必填，命名和升级跟随 OpenHarmony 版本号。|静态检查| +|name|string。部件的HPM（鸿蒙包管理器）包名称，必填。命名规则：@{organization}/{component_name}。"component_name"为部件的名称，须满足规则1.1。|静态检查| +|version|string。部件版本号，必填，命名和升级跟随OpenHarmony版本号。|静态检查| |destPath|string。部件源码的根目录，必填。部件的根目录须独立唯一，不允许存在多个根目录。|静态检查| |component:name|string。部件名，必填。须满足规则1.1。|静态检查| |component:subsystem|string。部件归属的子系统名称，必填，子系统名为小写英文字母组合、不使用下划线。|静态检查| -|component:syscap|string list。可选。命名规则：大驼峰，"SystemCapability.Subsystem.部件能力.子能力（可选）"，如 `SystemCapability.Media.Camera`, `SystemCapability.Media.Camera.Front`。|静态检查| +|component:syscap|string list。系统能力的描述，可选。命名规则：大驼峰，"SystemCapability.Subsystem.部件能力.子能力（可选）"，如`SystemCapability.Media.Camera`,`SystemCapability.Media.Camera.Front`。|静态检查| |component:features|string list，部件可配置的特性，可选，命名须满足规则1.2。|静态检查| -|component:adapted_system_type|string list。部件适用的系统类型，必填，值为 `mini`、`small` 和 `standard`，可同时支持多种。|静态检查| -|component:rom|string。ROM基线值，必填，单位默认为 KByte。|静态检查| -|component:ram|string。RAM基线值，必填，单位默认为 KByte。|静态检查| -|component:deps|string list。deps 对象描述了部件的外部依赖，必填，包括其他部件和三方开源软件，应该与部件编译脚本中依赖一致。|预编译检查| +|component:adapted_system_type|string list。部件适用的系统类型，必填，值为`mini`、`small`和`standard`，可同时支持多种。|静态检查| +|component:rom|string。ROM基线值，必填，单位默认为KByte。|静态检查| +|component:ram|string。RAM基线值，必填，单位默认为KByte。|静态检查| +|component:deps|string list。deps对象描述了部件的外部依赖，必填，包括其他部件和三方开源软件，应该与部件编译脚本中依赖一致。|预编译检查| ### 建议2.1 部件的描述文件应存放在部件根目录下 -部件目录是独立的，应将 bundle.json 文件存放到部件根目录下。 +部件目录是独立的，应将bundle.json文件存放到部件根目录下。 ## 3 变量 @@ -119,27 +119,27 @@ bundle.json 是定义部件的描述文件，包含了部件的根目录、名 ### 规则3.1 部件编译脚本中只允许引用本部件的路径，禁止引用其他部件的绝对或相对路径 -部件间的依赖都必须使用 "externel_deps"，部件编译目标的变量 sources、include_dirs、configs、public_configs、deps、public_deps 引用其他部件的相对和绝对路径属于非法引入依赖： +部件间的依赖都必须使用"externel_deps"，部件编译目标的变量sources、include_dirs、configs、public_configs、deps、public_deps引用其他部件的相对和绝对路径属于非法引入依赖： - sources - sources 只允许包含本部件的源码，包含其他部件的源码破坏了部件源码目录独立的原则。 + sources只允许包含本部件的源码，包含其他部件的源码破坏了部件源码目录独立的原则。 - include_dirs - include_dirs 只允许引用本部件的头文件搜索路径，编译单元对其他部件的接口的依赖都通过 externel_deps 自动导入。 + include_dirs只允许引用本部件的头文件搜索路径，编译单元对其他部件的接口的依赖都通过externel_deps自动导入。 - configs - configs 只允许引用本部件的配置路径，引用其他部件的 configs 可能会引入接口依赖。 + configs只允许引用本部件的配置路径，引用其他部件的configs可能会引入接口依赖。 - pulic_configs - pulic_configs 只允许引用本部件的配置路径，引用其他部件的 configs 可能会引入接口依赖。 + pulic_configs只允许引用本部件的配置路径，引用其他部件的configs可能会引入接口依赖。 - deps - deps 只允许用于部件内模块的依赖，直接引用其他部件的模块可能会导致依赖其他部件的内部模块和接口。 + deps只允许用于部件内模块的依赖，直接引用其他部件的模块可能会导致依赖其他部件的内部模块和接口。 例： @@ -148,24 +148,25 @@ bundle.json 是定义部件的描述文件，包含了部件的根目录、名 ```c deps = [ "//base/foo/foo_b:b" ] // Bad, 绝对路径依赖其他部件 deps = [ "../../foo_b:b" ] // Bad, 相对路径依赖其他部件 + deps = [ "a" ] // Good, 依赖当前部件内的其他模块 ``` > ![icon-note.gif](public_sys-resources/icon-note.gif) **例外：** 对三方开源软件的引用除外。 - public_deps - public_deps 只允许用于部件内模块的依赖，直接引用其他部件的模块可能会导致依赖其他部件的内部模块和接口。 + public_deps只允许用于部件内模块的依赖，直接引用其他部件的模块可能会导致依赖其他部件的内部模块和接口。 > ![icon-note.gif](public_sys-resources/icon-note.gif) **例外：** 对三方开源软件的引用除外。 -**看护手段：** 静态检查 +看护手段：静态检查 ### 规则3.2 部件编译目标必须指定部件和子系统名 -部件的编译单元 ohos_shared_library、ohos_static_library、ohos_executable_library、ohos_source_set 都必须指定 "part_name" 和 "subsystem_name"。 +部件的编译单元ohos_shared_library、ohos_static_library、ohos_executable_library、ohos_source_set都必须指定"part_name"和"subsystem_name"。 -**看护手段：** 静态检查 +看护手段：静态检查 ### 建议3.1 部件内部的引用使用相对路径 @@ -191,7 +192,7 @@ deps = [ ] ``` -**看护手段：** 静态检查 +看护手段：静态检查 ### 建议3.2 部件内部模块的可见度设置为部件内可见 @@ -215,19 +216,19 @@ ohos_shared_library("foo_a") { 部件是通用的系统能力，与特定产品无关。编译脚本中使用产品名称，将导致部件功能与产品绑定，不具备通用性。部件不同产品形态上的差异应抽象为特性或者运行时的插件。 -> ![icon-note.gif](public_sys-resources/icon-note.gif)**例外：** vendor 和 device 目录下三方厂商部件的编译脚本例外。 +> ![icon-note.gif](public_sys-resources/icon-note.gif)**例外：** vendor和device目录下三方厂商部件的编译脚本例外。 -**看护手段：** 静态检查 +看护手段：静态检查 ### 建议4.1 避免import其他部件目录下的gni文件 -部件内的 gni 文件是用于声明部件内部编译变量和模板，import 其他部件的 gni 文件等同于使用其他部件内部的变量和模板，即引入对其他部件的依赖。影响多个部件的变量、args 和模板应定义在编译框架的 gni 文件中。 +部件内的gni文件用于声明部件内部编译变量和模板，import其他部件的gni文件等同于使用其他部件内部的变量和模板，即引入对其他部件的依赖。影响多个部件的变量、args和模板应定义在编译框架的gni文件中。 -> ![icon-note.gif](public_sys-resources/icon-note.gif)**例外：** build 目录下编译框架定义全局的编译选项的 gni 可以被所有部件 import。 +> ![icon-note.gif](public_sys-resources/icon-note.gif)**例外：** build目录下编译框架定义全局的编译选项的gni可以被所有部件import。 -**看护手段：** 静态检查 +看护手段：静态检查 ### 建议4.2 部件使用统一的编译单元模板 -轻量、小型和标准的系统的编译单元都应使用ohos定义的模板，比如 `ohos_shared_library`、`ohos_static_library`、`ohos_executable_library`、`ohos_source_set` 等以 "ohos_" 为前缀的模板。 +轻量、小型和标准的系统的编译单元都应使用ohos定义的模板，比如`ohos_shared_library`、`ohos_static_library`、`ohos_executable_library`、`ohos_source_set`等以"ohos_"为前缀的模板。