alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Merge branch 'docs/add_component_manager_to_build_system' into 'master'

Browse Source 
Docs/add component manager to build system

See merge request espressif/esp-idf!29064
This commit is contained in:
Daniel Paul 2024-05-30 22:47:49 +08:00
commit 26502b7e2e
2 changed files with 44 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
docs/en/api-guides/build-system.rst
View File

@ -149,11 +149,14 @@ Example Project
.. highlight:: none
An example project directory tree might look like this::
An example project directory tree might look like this:
.. code-block:: none
- myProject/
- CMakeLists.txt
- sdkconfig
- dependencies.lock
- bootloader_components/ - boot_component/ - CMakeLists.txt
- Kconfig
- src1.c
@ -164,10 +167,14 @@ An example project directory tree might look like this::
- Kconfig
- src1.c
- include/ - component2.h
- managed_components/ - namespace__component-name/ - CMakelists.txt
- src1.c
- idf_component.yml
- include/ - src1.h
- main/ - CMakeLists.txt
- src1.c
- src2.c
- idf_component.yml
- build/
This example "myProject" contains the following elements:
@ -176,6 +183,10 @@ This example "myProject" contains the following elements:
- "sdkconfig" project configuration file. This file is created/updated when ``idf.py menuconfig`` runs, and holds the configuration for all of the components in the project (including ESP-IDF itself). The ``sdkconfig`` file may or may not be added to the source control system of the project.
- "dependencies.lock" file contains the list of all managed components, and their versions, that are currently in used in the project. The ``dependencies.lock`` file is generated or updated automatically when IDF Component Manager is used to add or update project components. So this file should never be edited manually! If the project does not have ``idf_component.yml`` files in any of its components, ``dependencies.lock`` will not be created.
- Optional "idf_component.yml" file contains metadata about the component and its dependencies. It is used by the IDF Component Manager to download and resolve these dependencies. More information about this file can be found in the `idf_component.yml <https://docs.espressif.com/projects/idf-component-manager/en/latest/reference/manifest_file.html>`_ section.
- Optional "bootloader_components" directory contains components that need to be compiled and linked inside the bootloader project. A project does not have to contain custom bootloader components of this kind, but it can be useful in case the bootloader needs to be modified to embed new features.
- Optional "components" directory contains components that are part of the project. A project does not have to contain custom components of this kind, but it can be useful for structuring reusable code or including third-party components that aren't part of ESP-IDF. Alternatively, ``EXTRA_COMPONENT_DIRS`` can be set in the top-level CMakeLists.txt to look for components in other places.
@ -184,6 +195,8 @@ This example "myProject" contains the following elements:
- "build" directory is where the build output is created. This directory is created by ``idf.py`` if it doesn't already exist. CMake configures the project and generates interim build files in this directory. Then, after the main build process is run, this directory will also contain interim object files and libraries as well as final binary output files. This directory is usually not added to source control or distributed with the project source code.
- "managed_components" directory is created by the IDF Component Manager to store components managed by this tool. Each managed component typically includes a ``idf_component.yml`` manifest file defining the component's metadata, such as version and dependencies. However, for components sourced from Git repositories, the manifest file is optional. Users should avoid manually modifying the contents of the "managed_components" directory. If alterations are needed, the component can be copied to the ``components`` directory. The "managed_components" directory is usually not versioned in Git and not distributed with the project source code.
Component directories each contain a component ``CMakeLists.txt`` file. This file contains variable definitions to control the build process of the component, and its integration into the overall project. See `Component CMakeLists Files`_ for more details.
Each component may also include a ``Kconfig`` file defining the `component configuration`_ options that can be set via ``menuconfig``. Some components may also include ``Kconfig.projbuild`` and ``project_include.cmake`` files, which are special files for `overriding parts of the project`_.
@ -338,6 +351,7 @@ The following component-specific variables are available for use inside componen
- ``COMPONENT_NAME``: Name of the component. Same as the name of the component directory.
- ``COMPONENT_ALIAS``: Alias of the library created internally by the build system for the component.
- ``COMPONENT_LIB``: Name of the library created internally by the build system for the component.
- ``COMPONENT_VERSION``: Component version specified by idf_component.yml and set by IDF Component Manager.
The following variables are set at the project level, but available for use in component CMakeLists:
@ -1548,6 +1562,10 @@ Enumeration
- Retrieve each component's public and private requirements. A child process is created which executes each component's CMakeLists.txt in script mode. The values of ``idf_component_register`` REQUIRES and PRIV_REQUIRES argument is returned to the parent build process. This is called early expansion. The variable ``CMAKE_BUILD_EARLY_EXPANSION`` is defined during this step.
- Recursively include components based on public and private requirements.
- Unless IDF Component Manager is disabled, it is called to resolve the dependencies of the components:
- Looks for manifests and dependencies contained in the project.
- Starts the version solving process to resolve the dependencies of the components.
- When the version solving process succeeds, the IDF Component Manager downloads dependencies, integrates them into the build, and creates a ``dependencies.lock`` file that contains a list of the exact versions of the dependencies installed by the IDF Component Manager.
Processing

30
docs/zh_CN/api-guides/build-system.rst
View File

@ -1,9 +1,9 @@
构建系统
********************
********
:link_to_translation:`en:[English]`
本文档主要介绍 ESP-IDF 构建系统的实现原理以及 ``组件`` 等相关概念。如需了解如何组织和构建新的 ESP-IDF 项目或组件，请阅读本文档。
本文档主要介绍 ESP-IDF 构建系统的实现原理以及“组件”等相关概念。如需了解如何组织和构建新的 ESP-IDF 项目或组件，请阅读本文档。
概述
@ -149,11 +149,14 @@ ESP-IDF 适用于 Python 3.8 以上版本。
.. highlight:: none
示例项目的目录树结构可能如下所示::
示例项目的目录树结构可能如下所示：
.. code-block:: none
- myProject/
- CMakeLists.txt
- sdkconfig
- dependencies.lock
- bootloader_components/ - boot_component/ - CMakeLists.txt
- Kconfig
- src1.c
@ -164,10 +167,14 @@ ESP-IDF 适用于 Python 3.8 以上版本。
- Kconfig
- src1.c
- include/ - component2.h
- managed_components/ - namespace__component-name/ - CMakelists.txt
- src1.c
- idf_component.yml
- include/ - src1.h
- main/ - CMakeLists.txt
- src1.c
- src2.c
- idf_component.yml
- build/
该示例项目 "myProject" 包含以下组成部分：
@ -176,14 +183,20 @@ ESP-IDF 适用于 Python 3.8 以上版本。
- "sdkconfig" 项目配置文件，执行 ``idf.py menuconfig`` 时会创建或更新此文件，文件中保存了项目中所有组件（包括 ESP-IDF 本身）的配置信息。 ``sdkconfig`` 文件可能会也可能不会被添加到项目的源码管理系统中。
- 可选的 "bootloader_components" 目录中包含了需要在引导加载项目中进行编译和链接的组件。并不是每个项目都需要这种自定义组件，但此类组件在引导加载程序需要修改以嵌入新功能时可能很有用。
- "dependencies.lock" 文件包含项目中当前使用的所有托管的组件及其版本。使用 IDF 组件管理器添加或更新项目组件时，会自动生成或更新 ``dependencies.lock`` 文件。因此，请勿手动编辑此文件！如果项目中没有组件包含 ``idf_component.yml`` 文件，则不会创建 ``dependencies.lock`` 文件。
- 可选的 "components" 目录中包含了项目的部分自定义组件，并不是每个项目都需要这种自定义组件，但它有助于构建可复用的代码或者导入第三方（不属于 ESP-IDF）的组件。或者，你也可以在顶层 CMakeLists.txt 中设置 ``EXTRA_COMPONENT_DIRS`` 变量以查找其他指定位置处的组件。
- “idf_component.yml” 是可选文件，里面包含组件的元数据及其依赖项。IDF 组件管理器使用该文件下载和解析这些依赖项。更多信息，请参阅 `idf_component.yml <https://docs.espressif.com/projects/idf-component-manager/en/latest/reference/manifest_file.html>`_。
- "bootloader_components" 是可选目录，里面包含了需要在引导加载项目中进行编译和链接的组件。并不是每个项目都需要这种自定义组件，但此类组件在引导加载程序需要修改以嵌入新功能时可能很有用。
- "components" 是可选目录，里面包含了项目的部分自定义组件，并不是每个项目都需要这种自定义组件，但它有助于构建可复用的代码或者导入第三方（不属于 ESP-IDF）的组件。或者，你也可以在顶层 CMakeLists.txt 中设置 ``EXTRA_COMPONENT_DIRS`` 变量以查找其他指定位置处的组件。
- "main" 目录是一个特殊的组件，它包含项目本身的源代码。"main" 是默认名称，CMake 变量 ``COMPONENT_DIRS`` 默认包含此组件，但你可以修改此变量。有关详细信息，请参阅 :ref:`重命名 main 组件 <rename-main>`。如果项目中源文件较多，建议将其归于组件中，而不是全部放在 "main" 中。
- "build" 目录是存放构建输出的地方，如果没有此目录，``idf.py`` 会自动创建。CMake 会配置项目，并在此目录下生成临时的构建文件。随后，在主构建进程的运行期间，该目录还会保存临时目标文件、库文件以及最终输出的二进制文件。此目录通常不会添加到项目的源码管理系统中，也不会随项目源码一同发布。
- "managed_components" 目录由 IDF 组件管理器创建，用于存储由 IDF 组件管理器管理的组件。每个托管组件通常包含 ``idf_component.yml`` 清单文件，定义了包括版本和依赖项在内的组件元数据。但对于那些来自 Git 仓库的组件，清单文件是可选的。请勿手动修改 "managed_components" 目录下的内容。如果需要进行更改，可以将组件复制到 ``components`` 目录下。"managed_components" 目录通常不在 Git 中进行版本控制，也不会与项目源代码一起分发。
每个组件目录都包含一个 ``CMakeLists.txt`` 文件，里面会定义一些变量以控制该组件的构建过程，以及其与整个项目的集成。更多详细信息请参阅 :ref:`component-directories`。
每个组件还可以包含一个 ``Kconfig`` 文件，它用于定义 ``menuconfig`` 时展示的 :ref:`component-configuration` 选项。某些组件可能还会包含 ``Kconfig.projbuild`` 和 ``project_include.cmake`` 特殊文件，它们用于 :ref:`override_project_config`。
@ -338,6 +351,7 @@ ESP-IDF 在搜索所有待构建的组件时，会按照 ``COMPONENT_DIRS`` 指
- ``COMPONENT_NAME``：组件名，与组件目录名相同。
- ``COMPONENT_ALIAS``：库别名，由构建系统在内部为组件创建。
- ``COMPONENT_LIB``：库名，由构建系统在内部为组件创建。
- ``COMPONENT_VERSION``：组件版本，由 idf_component.yml 指定并由 IDF 组件管理器设置。
以下变量在项目级别中被设置，但可在组件 CMakeLists 中使用：
@ -1548,6 +1562,10 @@ ESP-IDF 构建系统的列表文件位于 :idf:`/tools/cmake` 中。实现构建
- 检索每个组件的公共和私有依赖。创建一个子进程，以脚本模式执行每个组件的 CMakeLists.txt。``idf_component_register`` REQUIRES 和 PRIV_REQUIRES 参数的值会返回给父进程。这就是所谓的早期扩展。在这一步中定义变量 ``CMAKE_BUILD_EARLY_EXPANSION``。
- 根据公共和私有的依赖关系，递归地导入各个组件。
- 若未禁用 IDF 组件管理器，则可调用它来解析组件的依赖项：
- 查找项目中包含的清单和依赖项。
- 启动版本解决过程以解析组件的依赖项。
- 若版本解决过程成功，则 IDF 组件管理器会下载依赖项，并将它们集成到构建中，随后创建 ``dependencies.lock`` 文件，该文件中包含上述依赖项的确切版本列表。
处理