diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst index b7b9b0ce8bc..bec630be8b0 100644 --- a/docs/en/api-guides/build-system.rst +++ b/docs/en/api-guides/build-system.rst @@ -168,9 +168,9 @@ Configdep Wrapper The ``esp-idf-configdep`` tool post-processes compiler-generated dependency files to reduce unnecessary rebuilds caused by ``sdkconfig.h`` changes. -Normally, every source file that includes ``sdkconfig.h`` would be rebuilt whenever any configuration option changes, because the compiler records ``sdkconfig.h`` as a direct dependency. The configdep tool edits the dependency files after the initial build so that source files no longer depend directly on ``sdkconfig.h``. Instead, they depend on a special file structure created by ``esp-idf-kconfig``: each configuration option has its own file, and when a given option is changed, only the corresponding file is touched. That way only the source files that actually use the changed option are rebuilt, not the entire project. +Normally, every source file that includes ``sdkconfig.h`` would be rebuilt whenever any configuration option changes, because the compiler records ``sdkconfig.h`` as a direct dependency. The Configdep tool edits the dependency files after the initial build so that source files no longer depend directly on ``sdkconfig.h``. Instead, they depend on a special file structure created by ``esp-idf-kconfig``: each configuration option has its own file, and when a given option is changed, only the corresponding file is touched. That way only the source files that actually use the changed option are rebuilt, not the entire project. -Important: source files are not modified. They still contain ``#include `` and there is no need to alter anything in the source code for configdep to work. The tool operates purely on the generated dependency (``.d``) files. +Important: source files are not modified. They still contain ``#include `` and there is no need to alter anything in the source code for Configdep to work. The tool operates purely on the generated dependency (``.d``) files. This is particularly useful when there are frequent changes of a small number of config options between rebuilds. Configdep is enabled by default. @@ -184,7 +184,7 @@ When multiple acceleration tools are enabled, they are chained together as compi 1. **esp-idf-configdep** (if enabled) - processes dependency files and optimizes rebuilds caused by ``sdkconfig.h`` changes 2. **ccache** (if enabled) - caches compilations -Each tool in the chain wraps the next, ultimately invoking the actual compiler. This allows combining the benefits of multiple tools. However, combining multiple tools may not always result in optimal performance and it may be needed to experiment with different combinations of the acceleration tools to achieve the best performance for your project. +Each tool in the chain wraps the next, ultimately invoking the actual compiler. This allows combining the benefits of multiple tools. However, combining multiple tools may not always result in optimal performance, and it may be needed to experiment with different combinations of the acceleration tools to achieve the best performance for your project. .. _example-project-structure: diff --git a/docs/zh_CN/api-guides/build-system.rst b/docs/zh_CN/api-guides/build-system.rst index 17f22a55023..2f41f4d8971 100644 --- a/docs/zh_CN/api-guides/build-system.rst +++ b/docs/zh_CN/api-guides/build-system.rst @@ -159,7 +159,7 @@ ESP-IDF 支持多种用于加速构建过程的工具。这些工具充当编译 CCache ^^^^^^ -CCache_ 是编译器缓存，通过缓存先前的编译结果来加速重新编译。启用后，当使用相同的源代码和编译器标志重复编译时，CCache 会直接返回缓存结果，而无需重新编译。 +CCache_ 是一种编译器缓存工具，通过缓存先前的编译结果来加速重新编译。启用后，当使用相同的源代码和编译器标志重复编译时，CCache 会直接返回缓存结果，而无需重新编译。 关于如何启用或禁用 CCache，请参见 :ref:`idf_py_global_options` 章节。 @@ -168,9 +168,9 @@ Configdep 封装器 ``esp-idf-configdep`` 工具对编译器生成的依赖文件进行后处理，以减少由 ``sdkconfig.h`` 变更引起的不必要重建。 -通常在任一配置选项发生变化时，凡是包含 ``sdkconfig.h`` 的源文件都会被重建，因为编译器会将 ``sdkconfig.h`` 记录为直接依赖。configdep 工具会在初次构建后编辑这些依赖文件，使源文件不再直接依赖 ``sdkconfig.h``。取而代之的是，源文件会依赖由 ``esp-idf-kconfig`` 创建的一种特殊文件结构：每个配置选项都有各自的文件，当某个选项被修改时，只会更新对应的文件。这样一来，只有实际使用到该变更选项的源文件会被重建，而并非整个项目。 +通常在任一配置选项发生变化时，凡是包含 ``sdkconfig.h`` 的源文件都会被重建，因为编译器会将 ``sdkconfig.h`` 记录为直接依赖。Configdep 工具会在初次构建后编辑这些依赖文件，使源文件不再直接依赖 ``sdkconfig.h``。取而代之的是，源文件会依赖由 ``esp-idf-kconfig`` 创建的一种特殊文件结构：每个配置选项都有各自的文件，当某个选项被修改时，只会更新对应的文件。这样一来，只有实际使用到该变更选项的源文件会被重建，而并非整个项目。 -重要：源文件不会被修改，仍然包含 ``#include ``，并且无需更改源代码中的任何内容，configdep 工具即可正常工作。该工具完全基于生成的依赖文件 (``.d``) 进行工作。 +重要：源文件不会被修改，仍然包含 ``#include ``，并且无需更改源代码中的任何内容，Configdep 工具即可正常工作。该工具仅作用于生成的依赖文件 (``.d``) 进行工作。 若重建时仅有少量配置选项频繁变更，该工具尤为有用。Configdep 默认启用。 @@ -179,12 +179,12 @@ Configdep 封装器 串联使用加速工具 ^^^^^^^^^^^^^^^^ -多个加速工具被启用时，会作为编译器启动器被串联起来，并按特定顺序应用： +启用多个加速工具时，它们会以编译器启动器链的形式串联使用。该链按照以下顺序应用： 1. **esp-idf-configdep** （若启用） - 处理依赖文件并优化由 ``sdkconfig.h`` 变更引起的重建 2. **ccache** （若启用） - 缓存编译结果 -链中的每个工具都会嵌套调用下一个工具，最终调用实际的编译器。这样可以叠加多个工具的优势。然而，组合使用多个工具并不总能带来最佳性能，可能需要尝试不同的工具组合，从而让项目达到最佳的构建性能。 +链中的每个工具都会封装下一个工具，最终调用实际的编译器。这样可以叠加多个工具的优势。然而，组合使用多个工具并不总能带来最佳性能，因此可能需要针对具体项目尝试不同的工具组合，以获得最佳构建性能。 .. _example-project-structure: