新增组件模块

本文介绍如何在现有组件仓下创建可复用的组件模块。

步骤
附录

步骤

下表为项目内已有的组件仓，根据实际情况在对应仓下添加模块。

跨功能域的模块，优先归属于最紧密的仓。

仓	定位	典型模块
`adapter`	硬件抽象与驱动适配，屏蔽芯片差异，为上层提供统一 HAL 接口	drivers（LCD、Touch、ADC、Flash、Sensor 等外设驱动）、wifi（ws53/ws73 等芯片适配）、hal
`hiai`	AI 能力组件，提供云端 Agent 接入、离线语音识别等端侧 AI 功能	adapt（AI 厂商适配）、cloud_agent（云端 AI Agent）、offline_voice（离线语音识别）、postprocess（AI 后处理）、xclaws（Zeroclaw 控制）
`hichannel`	通道管理组件	数据通道、流分发
`media`	媒体与显示组件，支持图形输出、UI 渲染、事件分发、媒体管线与进程间通信	eventhub（事件总线）、framework（媒体进程间通信框架）、log（媒体日志）、pipeline（媒体管线）、python_api（AI 检测/媒体/录制脚本接口）
`network`	网络通信组件，提供基础网络接口、RTSP 直播推流与速率控制	livestream（RTSP 直播推流）、mbuffer（内存缓冲管理）、mcu_transfer_protocol（MCU 传输协议）、ot_autorate（速率控制）

创建模块

1.模仿下文创建标准的模块目录结构：

components/<component_repo>/<module>/
├── CMakeLists.txt       # 模块构建入口
├── include/             # 对外头文件
│   └── <module>.h
├── src/                 # 实现源码
│   └── *.c
└── README.md            # 组件说明(参考项目相关模板)

2.参考其他组件模块编写 CMakeLists.txt

CMakeLists.txt 的行为取决于 src/ 下是否存在 .c 源文件： - 有 .c 文件时：编译为静态库（.a），链接方可调用模块函数； - 无 .c 文件时：仅导出 include/ 下的头文件路径，不生成编译产物。

无论哪种情形，依赖本模块的目标均能访问 include/ 下的头文件。后续在 src/ 添加 .c 文件并重新编译，CMake 自动切换为静态库，无需修改 CMakeLists.txt 或引用方。

如果模块有外部依赖时，需在 CMakeLists.txt 中追加 target_link_libraries 声明。

3.编写 README.md：

仓级 README（components/<repo>/README.md）：一句话说明仓内模块的共同定位，以及仓内各个模块的功能概述。
模块级 README 模块对外API参考统一写入 docs\zh-CN\software-guide\api-reference 目录下，不放在模块中。

若模块引入或内联了第三方开源代码，按添加第三方开源组件完成合规登记。

注册到构建系统

在新增模块归属仓的 CMakeLists.txt（如 components/media/CMakeLists.txt）中追加子目录选项：

add_subdirectory(<module>)

adapter 仓下的驱动类模块（放置在 drivers/ 下），若模块需随 rootfs 默认编译，在 components/adapter/drivers/CMakeLists.txt 中追加 add_subdirectory，并通过 add_dependencies 将模块声明为 drv_all 的依赖：

add_dependencies(drv_all <module>)

drv_all 是 adapter 的驱动聚合编译目标，rootfs编译构建依赖该目标来收集驱动产物。

可选：添加独立 Kconfig 开关

模块默认随组件仓一起编译。若需独立控制开关，按以下命名规范添加 Kconfig 配置项，并在模块 CMakeLists.txt 顶部添加编译守卫。

命名规范

模块类型	Kconfig 前缀	示例
Adapter 驱动	`DRV_<SUBSYSTEM>_`	`DRV_LCD_ST7789V`
其他组件模块	`COMP_<REPO>_`	`COMP_HIAI_AUDIO`

在模块所属子系统的就近 Kconfig 中添加 config 项。例如，新增 LCD 驱动在 components/adapter/drivers/lcd/Kconfig 中追加，驱动开关已按子系统拆分到：

components/adapter/drivers/lcd/Kconfig — LCD 驱动
components/adapter/drivers/touch/Kconfig — 触摸驱动
components/adapter/drivers/adc/Kconfig — ADC 驱动
components/adapter/wifi/ws73/Kconfig — Wi-Fi 驱动

kconfig2cmake.py 自动将任何 CONFIG_DRV_* 符号转换为 ENABLE_DRV_* CMake 变量，无需手动注册映射。具体写法参考同子系统下已有模块的 Kconfig 条目。

在模块的 CMakeLists.txt 顶部添加以下判断，使模块在未开启时跳过编译：

if(NOT ENABLE_<YOUR_CONFIG>)
    return()
endif()

其中 <YOUR_CONFIG> 为 Kconfig 符号名加 ENABLE_ 前缀（如 DRV_LCD_ST7789V → ENABLE_DRV_LCD_ST7789V）。

验证

在案例的 app.defconfig 中启用对应组件仓：

CONFIG_COMP_<REPO>=y

若模块配有独立 Kconfig 开关，在 app.defconfig 中追加 CONFIG_<KCONFIG_NAME>=y（如 CONFIG_DRV_LCD_ST7789V=y）。

执行编译：

bash scripts/build.sh build --target cv610_ev_board references <test_app>

确认 _build/lib/ 下生成了对应的静态库文件。

文档	说明
构建文档	编译命令、烧写方法与产物说明
新增 sample（单点功能示例）	创建示例目录、编写 app.defconfig 和 CMakeLists.txt
添加第三方开源组件	开源库注册与合规登记
模块API参考	组件启用、链接与 API 调用

新增组件模块

步骤

创建模块

注册到构建系统

验证

附录

相关文档