esp-idf-components

ESP-IDF 组件

适用场景

• 创建项目本地组件或可独立复用的组件。
• 在 Registry 依赖项和新实现之间做出选择。
• 定义组件 API、CMake 依赖项、Kconfig、清单、测试或 CI。
• 准备或审核 ESP Component Registry 软件包。

工作流

1. 判断是否需要新组件

• 先搜索 ESP Component Registry。优先使用 Registry MCP 工具（如果可用），并将公共 API 或网站作为备选。
• 根据 ESP-IDF 和目标兼容性、维护情况、许可证及 API 适配度比较候选项。仅当剩余选择会产生实质影响时才询问用户。
• 使用合适的现有组件，而不是重复实现。
• 将产品专属代码放在应用的 components/ 下；独立版本管理的可复用代码则使用独立软件包。

2. 添加现有依赖项

• 在项目根目录运行 idf.py add-dependency "namespace/component^<VERSION>"；默认会更新 main。
• 对 components/ 下的组件使用 --component=<NAME>，对其他组件目录使用 --path=<PATH>。
• 需要确保可复现性时，明确指定版本约束。切勿手动编辑 dependencies.lock 或 managed_components/。

3. 搭建新组件的脚手架

• 使用 idf.py create-component <COMPONENT_NAME>，而不是手动生成样板代码。在目标父目录中运行，或使用 -C <PATH>。
• 对于本地组件，在 components/ 下搭建脚手架。
• 对于独立软件包，在其代码仓库根目录中搭建脚手架，并仅按需添加打包文件。
• 使用 idf.py create-manifest 创建清单；必要时使用 --component=<NAME> 或 --path=<PATH>。安装 Compote 后，compote manifest create 是 Component Manager 的现代等效命令。
• 阅读 references/component_manager.md，了解完整的 CLI、目录结构、Registry 和 CI 详情。

4. 使用清晰的目录结构

• 将公共头文件放在 include/ 中。
• 将实现文件和私有头文件放在公共包含目录之外。多个源文件共用私有头文件时，使用 PRIV_INCLUDE_DIRS 添加私有包含目录。
• 最小组件包含 CMakeLists.txt、include/<name>.h 和源文件。可复用软件包通常还会添加 idf_component.yml、README.md、LICENSE 以及至少一个示例或测试应用。
• 切勿编辑 build/ 下的生成文件。

5. 正确注册组件

• 在组件的 CMakeLists.txt 中使用 idf_component_register(...)。
• 明确声明 SRCS 和 INCLUDE_DIRS。
• 对通过组件公共头文件公开的公共依赖项使用 REQUIRES。
• 对仅用于实现的依赖项使用 PRIV_REQUIRES。
• 不要依赖偶然产生的传递依赖。

示例：

idf_component_register(
    SRCS "my_component.c"
    INCLUDE_DIRS "include"
    REQUIRES esp_timer
    PRIV_REQUIRES driver
)

6. 明确组件边界

• 保持公共 API 简洁且稳定。
• 除非它们属于预期的 API 范围，否则不要通过公共头文件泄露无关的 ESP-IDF 头文件。
• 对于非简单组件，优先使用不透明句柄、明确的 init/deinit 函数以及 esp_err_t 返回值。
• 将无关职责拆分为不同组件，而不是构建一个大型实用工具组件。

7. 有意识地使用配置文件

• 使用 Kconfig 配置组件级选项。
• 仅当选项必须出现在项目级 menuconfig 中时，才使用 Kconfig.projbuild。
• 为配置符号添加命名空间，例如 MY_COMPONENT_*。
• 每个新增配置选项都应包含：
  • 清晰的提示文本
  • 合理的默认值
  • 简短的帮助文本
• 修改 Kconfig 或 Kconfig.projbuild 后，询问是否运行 idf.py reconfigure。普通构建会检测定义变更，但已存储在 sdkconfig 中的值可能不会被更改后的默认值覆盖。

可复用组件检查清单

• 确保软件包不依赖应用程序全局变量、机密信息和硬编码的开发板选项。
• 当需要 Component Manager 元数据或依赖项时，以及在常规 Registry 发布前，添加 idf_component.yml。
• 添加 README.md，说明用途、配置、依赖项和用法。
• 如果组件将共享到项目之外，请添加 LICENSE 文件。
• 如果行为并非简单直观，请至少提供一个示例或测试应用。
• 添加 CI，至少构建支持的目标，并在存在示例或测试应用时对其进行验证。
• 保持 Kconfig 选项和默认值精简，并提供文档说明。
• 验证组件可针对其支持的目标顺利构建。
• 仅当确实计划发布组件时，才使用 Registry 上传流程。
• 要求提供新的 idf_component.yml version，然后 CI 才能发布更新后的 Registry 版本。

验证与交接

• 为组件支持的目标矩阵构建所有相关示例或测试应用。如果仓库 CI 定义了目标矩阵，请遵循该矩阵。
• 在组件根目录中使用 compote component pack --name <NAME> 验证软件包创建。
• 当 Registry 凭据和命名空间访问权限已获授权时，使用以下命令验证上传，但不实际发布： compote component upload --name <NAME> --namespace <NAMESPACE> --dry-run。
• 默认将发布工作流保持在 dry-run 模式。创建不可变的 Registry 版本前，必须明确选择生产发布。
• 报告 ESP-IDF 版本、构建的目标、运行的测试、软件包验证结果，以及任何未验证的内容。

避免

• 在检查是否已有现成依赖项之前，不要创建新的本地组件
• 不要将可复用组件模板用于 components/ 下仅供一次性项目使用的辅助程序
• 当应用代码具有明确的组件边界时，不要将其全部放入 main/
• 不要在公共头文件中暴露私有实现细节
• 当 PRIV_REQUIRES 已足够时，不要使用 REQUIRES
• 不要编辑 build/ 下生成的文件
• 不要手动编辑 managed_components/ 或 dependencies.lock
• 当默认值应放在 sdkconfig.defaults* 中时，不要在 sdkconfig 中进行大范围配置更改