diff --git a/docs/zh_CN/api-guides/build-system.rst b/docs/zh_CN/api-guides/build-system.rst index b3f72737849..17f22a55023 100644 --- a/docs/zh_CN/api-guides/build-system.rst +++ b/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 ``,并且无需更改源代码中的任何内容,configdep 工具即可正常工作。该工具完全基于生成的依赖文件 (``.d``) 进行工作。 + +若重建时仅有少量配置选项频繁变更,该工具尤为有用。Configdep 默认启用。 + +有关如何启用或禁用 Configdep,请参见 :ref:`idf_py_global_options` 章节。 + +串联使用加速工具 +^^^^^^^^^^^^^^^^ + +多个加速工具被启用时,会作为编译器启动器被串联起来,并按特定顺序应用: + +1. **esp-idf-configdep** (若启用) - 处理依赖文件并优化由 ``sdkconfig.h`` 变更引起的重建 +2. **ccache** (若启用) - 缓存编译结果 + +链中的每个工具都会嵌套调用下一个工具,最终调用实际的编译器。这样可以叠加多个工具的优势。然而,组合使用多个工具并不总能带来最佳性能,可能需要尝试不同的工具组合,从而让项目达到最佳的构建性能。 + .. _example-project-structure: 示例项目 diff --git a/docs/zh_CN/api-guides/tools/idf-py.rst b/docs/zh_CN/api-guides/tools/idf-py.rst index 36a62e79f9e..008eeb29d6c 100644 --- a/docs/zh_CN/api-guides/tools/idf-py.rst +++ b/docs/zh_CN/api-guides/tools/idf-py.rst @@ -459,6 +459,8 @@ ESP-IDF 支持 `CMake presets`_ 以简化多个构建配置的管理。此功能 完整示例请参阅 :example_file:`Multiple Build Configurations Example `。 +.. _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`` 用于禁用有关错误处理的提示并禁用捕获输出。