Merge branch 'feat/generate_per_component_headers' into 'master'

feat(kconfig): add support for per option based build optimization

Closes IDF-8957

See merge request espressif/esp-idf!41966

docs/zh_CN/api-guides/build-system.rst

@@ -149,6 +149,43 @@ ESP-IDF 适用于 Python 3.10 以上版本。
 如果想在命令行中更优雅地管理 Python 的各个版本，请查看 pyenv_ 或 virtualenv_ 工具，它们会帮助你更改默认的 python 版本。
 
 
+.. _build-acceleration:
+
+构建加速
+--------
+
+ESP-IDF 支持多种用于加速构建过程的工具。这些工具充当编译器启动器，封装并调用实际的编译器。
+
+CCache
+^^^^^^
+
+CCache_ 是一种编译器缓存工具，通过缓存先前的编译结果来加速重新编译。启用后，当使用相同的源代码和编译器标志重复编译时，CCache 会直接返回缓存结果，而无需重新编译。
+
+关于如何启用或禁用 CCache，请参见 :ref:`idf_py_global_options` 章节。
+
+Configdep 封装器
+^^^^^^^^^^^^^^^^^
+
+``esp-idf-configdep`` 工具对编译器生成的依赖文件进行后处理，以减少由 ``sdkconfig.h`` 变更引起的不必要重建。
+
+通常在任一配置选项发生变化时，凡是包含 ``sdkconfig.h`` 的源文件都会被重建，因为编译器会将 ``sdkconfig.h`` 记录为直接依赖。Configdep 工具会在初次构建后编辑这些依赖文件，使源文件不再直接依赖 ``sdkconfig.h``。取而代之的是，源文件会依赖由 ``esp-idf-kconfig`` 创建的一种特殊文件结构：每个配置选项都有各自的文件，当某个选项被修改时，只会更新对应的文件。这样一来，只有实际使用到该变更选项的源文件会被重建，而并非整个项目。
+
+重要：源文件不会被修改，仍然包含 ``#include <sdkconfig.h>``，并且无需更改源代码中的任何内容，Configdep 工具即可正常工作。该工具仅作用于生成的依赖文件 (``.d``) 进行工作。
+
+若重建时仅有少量配置选项频繁变更，该工具尤为有用。Configdep 默认启用。
+
+有关如何启用或禁用 Configdep，请参见 :ref:`idf_py_global_options` 章节。
+
+串联使用加速工具
+^^^^^^^^^^^^^^^^
+
+启用多个加速工具时，它们会以编译器启动器链的形式串联使用。该链按照以下顺序应用：
+
+1. **esp-idf-configdep** （若启用） - 处理依赖文件并优化由 ``sdkconfig.h`` 变更引起的重建
+2. **ccache** （若启用） - 缓存编译结果
+
+链中的每个工具都会封装下一个工具，最终调用实际的编译器。这样可以叠加多个工具的优势。然而，组合使用多个工具并不总能带来最佳性能，因此可能需要针对具体项目尝试不同的工具组合，以获得最佳构建性能。
+
 .. _example-project-structure:
 
 示例项目

docs/zh_CN/api-guides/tools/idf-py.rst

@@ -459,6 +459,8 @@ ESP-IDF 支持 `CMake presets`_ 以简化多个构建配置的管理。此功能
 
 完整示例请参阅 :example_file:`Multiple Build Configurations Example <build_system/cmake/multi_config/README.md>`。
 
+.. _idf_py_global_options:
+
 全局选项
 ==============
 
@@ -472,6 +474,8 @@ ESP-IDF 支持 `CMake presets`_ 以简化多个构建配置的管理。此功能
 
     注意，某些旧版本 CCache_ 在某些平台上存在 bug，因此如果文件没有按预期重新构建，可禁用 CCache_ 并重新构建。可以通过将环境变量 ``IDF_CCACHE_ENABLE`` 设置为非零值来默认启用 CCache_。
 
+- ``--configdep`` 或 ``--no-configdep`` 用于启用或禁用基于 ``esp-idf-configdep`` 的重建优化。该工具会对编译器生成的依赖文件进行后处理，以减少因 ``sdkconfig.h`` 变更而导致的不必要重建。若重建时仅有少量配置选项频繁变更，这一功能尤为有用。该功能默认启用。若要永久启用 configdep，请将 ``IDF_CONFIGDEP_ENABLE`` 环境变量设置为 ``1``；若要永久禁用，则设置为 ``0``。
+
 - ``-v`` 会使 ``idf.py`` 和构建系统生成详细的构建输出，有助于调试构建错误。
 - ``--cmake-warn-uninitialized`` （或 ``-w``）将使 CMake 只显示在工程目录中发现的变量未初始化的警告，该选项仅控制 CMake 内部的 CMake 变量警告，不控制其他类型的构建警告。将环境变量 ``IDF_CMAKE_WARN_UNINITIALIZED`` 设置为非零值，可永久启用该选项。
 - ``--no-hints`` 用于禁用有关错误处理的提示并禁用捕获输出。

docs/zh_CN/api-guides/tools/idf-tools-notes.inc

@@ -91,6 +91,11 @@ Some ESP-specific instructions for running QEMU for Xtensa chips are here: https
 
 Some ESP-specific instructions for running QEMU for RISC-V chips are here: https://github.com/espressif/esp-toolchain-docs/blob/main/qemu/esp32c3/README.md
 
+---
+
+.. tool-esp-idf-configdep-notes
+
+
 ---
 
 .. tool-idf-python-notes