警告
This document is not updated for ESP32C5 yet, so some of the content may not be correct.
This warning was automatically inserted due to the source file being in the add_warnings_pages list.
IDF 组件管理器
IDF 组件管理器工具用于下载 ESP-IDF CMake 项目的依赖项，该下载在 CMake 运行期间自动完成。IDF 组件管理器可以从 组件注册表 或 Git 仓库获取组件。
要获取组件列表，请参阅 https://components.espressif.com/.
有关 IDF 组件管理器的详细信息，请参阅 IDF 组件管理器及 ESP 组件注册表文档。
在项目中使用 IDF 组件管理器
项目中各组件的依赖项定义在单独的清单文件中，命名为 idf_component.yml，位于组件根目录。运行 idf.py create-manifest 可以为组件创建清单文件模板。默认情况下将为 main 组件创建清单文件。使用 --path 选项，可以显式指定创建清单文件的目录路径。使用 --component=my_component 选项可以指定组件名称，这样系统将会在 components 文件夹下为该组件创建清单文件。create-manifest 命令支持以下运行方式：
idf.py create-manifest为 main 组件创建清单文件idf.py create-manifest --component=my_component在components目录下，为组件 my_component 创建清单文件idf.py create-manifest --path="../../my_component"在my_component目录下，为组件 my_component 创建清单文件
在向项目的某个组件添加新的清单时，必须先运行 idf.py reconfigure，手动重新配置项目。随后，构建过程将跟踪 idf_component.yml 清单的变更，并在必要时自动触发 CMake。
要为 ESP-IDF 项目中的组件（如 my_component）添加依赖项，可以运行命令 idf.py add-dependency DEPENDENCY。DEPENDENCY 参数代表一个由 IDF 组件管理器管理的额外组件，而 my_component 也依赖于这个组件。DEPENDENCY 参数的格式为 namespace/name=1.0.0，namespace/name 代表组件名称，=1.0.0 是组件的版本范围，详情请参阅 版本文档。默认情况下，依赖项会添加到 main 组件。通过使用 --path 选项，可以显式指定包含清单的目录，也可以使用 --component=my_component，在 components 文件夹中指定组件。add-dependency 命令支持以下运行方式：
idf.py add-dependency example/cmp为 main 组件添加依赖项，依赖项为example/cmp的最新版本idf.py add-dependency --component=my_component example/cmp<=3.3.3将依赖项添加到位于components目录下名为my_component的组件中，依赖项为版本号<=3.3.3的example/cmpidf.py add-dependency --path="../../my_component" example/cmp^3.3.3将依赖项添加到位于目录my_component下名为my_component的组件中，依赖项为版本号^3.3.3的example/cmp
备注
add-dependency 命令会从 乐鑫组件注册表 将依赖项显式添加到你的项目中。
要更新 ESP-IDF 项目的依赖项，请运行命令 idf.py update-dependencies。你也可以使用 --project-dir PATH 选项，指定项目目录的路径。
应用程序示例 build_system/cmake/component_manager 使用了由组件管理器安装的组件。
对于不需要受管理依赖项的组件，则无需提供清单文件。
在 CMake 配置项目（如 idf.py reconfigure）时，组件管理器会执行以下操作：
处理项目中每个组件的
idf_component.yml清单，并递归解析依赖项。在项目根目录中创建
dependencies.lock文件，包含完整的依赖项列表。将所有依赖项下载至
managed_components目录。
请勿更改 dependencies.lock 锁文件和 managed_components 目录的内容。组件管理器运行时，会始终确保这些文件处于最新状态。如果意外修改了这些文件，可以通过使用 idf.py reconfigure 触发 CMake，重新运行组件管理器。
设置构建属性 DEPENDENCIES_LOCK 可以指定顶层 CMakeLists.txt 文件中的锁文件路径。例如，在 project(PROJECT_NAME) 前添加 idf_build_set_property(DEPENDENCIES_LOCK dependencies.lock.${IDF_TARGET})，可以为不同目标生成不同锁文件。
从示例创建项目
组件注册表中，部分组件包含示例项目。要从示例创建一个新项目，可以运行命令 idf.py create-project-from-example EXAMPLE。EXAMPLE 参数格式为 namespace/name=1.0.0:example，namespace/name 代表组件名称，=1.0.0 是组件的版本范围（详情请参阅 版本文档），而 example 代表示例名称。在 乐鑫组件注册表 中，可以找到各组件的示例列表，以及启动组件示例的相应命令。
在清单文件中定义依赖项
通过在文本编辑器直接编辑，你可以轻松定义清单文件 idf_component.yml 中的依赖项。以下是有关定义依赖项的简单示例：
你可以通过指定组件名称和版本范围，定义来自注册表的依赖项：
dependencies:
# 定义来自注册表 (https://components.espressif.com/component/example/cmp) 的依赖项
example/cmp: ">=1.0.0"
要从 Git 仓库定义依赖关系，请提供组件在仓库中的路径和仓库的 URL：
dependencies:
# 从 Git 仓库定义依赖项
test_component:
path: test_component
git: ssh://git@gitlab.com/user/components.git
在开发组件时，可以通过指定相对或绝对路径，使用本地目录中的组件：
dependencies:
# 通过相对路径定义本地依赖项
some_local_component:
path: ../../projects/component
有关清单文件格式的详细信息，请参阅 清单文件格式文档。
禁用组件管理器
将环境变量 IDF_COMPONENT_MANAGER 设置为 0，可以显式禁用组件管理器。