From 7356b34389ab41f3db562dae785ed7a19559498b Mon Sep 17 00:00:00 2001 From: Jan Beran Date: Fri, 27 Feb 2026 12:08:06 +0100 Subject: [PATCH 1/2] docs: clarify how SDKCONFIG_DEFAULTS cache variable works --- docs/en/api-guides/build-system.rst | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst index 788a174c75..778db9c4c9 100644 --- a/docs/en/api-guides/build-system.rst +++ b/docs/en/api-guides/build-system.rst @@ -1100,7 +1100,33 @@ If and only if an ``sdkconfig.defaults`` file exists, the build system will also If ``SDKCONFIG_DEFAULTS`` is used to override the name of defaults file/files, the name of target-specific defaults file will be derived from ``SDKCONFIG_DEFAULTS`` value/values using the rule above. When there are multiple files in ``SDKCONFIG_DEFAULTS``, target-specific file will be applied right after the file bringing it in, before all latter files in ``SDKCONFIG_DEFAULTS`` -For example, if ``SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig_devkit1"``, and there is a file ``sdkconfig.defaults.esp32`` in the same folder, then the files will be applied in the following order: (1) sdkconfig.defaults (2) sdkconfig.defaults.esp32 (3) sdkconfig_devkit1. +For the following example, suppose the build target is ``esp32`` and these files exist in the project directory: + +.. code-block:: none + + sdkconfig.defaults + sdkconfig.defaults.esp32 + sdkconfig_devkit1 + +**Example 1**: ``SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig_devkit1"`` + +The build system will apply the files in this order: + +1. ``sdkconfig.defaults`` +2. ``sdkconfig.defaults.esp32`` - build system will always try to load target specific variation of every file listed in ``SDKCONFIG_DEFAULTS`` +3. ``sdkconfig_devkit1`` +4. The build system will also attempt to load a file named ``sdkconfig_devkit1.esp32``, but because there is no file with this name, no additional file will be loaded. + +**Example 2**: ``SDKCONFIG_DEFAULTS="sdkconfig_devkit1"`` + +The build system will apply the files in this order: + +1. ``sdkconfig_devkit1`` +2. The build system will also attempt to load a file named ``sdkconfig_devkit1.esp32``, but because there is no file with this name, no additional file will be loaded. + +.. warning:: + + In the second example, the standard ``sdkconfig.defaults`` (or its target specific variation) is not applied, because it was not explicitly included in ``SDKCONFIG_DEFAULTS``. You can find more detailed information on how the project configuration works in the :ref:`Project Configuration Guide `. In the :ref:`Configuration Files Structure and Relationships `, you can find lower-level information about the configuration files. From d188a9faa47defed265b49d60343ef3bea0ffbd9 Mon Sep 17 00:00:00 2001 From: renpeiying Date: Thu, 26 Mar 2026 14:59:21 +0800 Subject: [PATCH 2/2] docs: Add CN translation --- docs/en/api-guides/build-system.rst | 14 ++++++------- docs/zh_CN/api-guides/build-system.rst | 28 +++++++++++++++++++++++++- 2 files changed, 34 insertions(+), 8 deletions(-) diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst index 778db9c4c9..ededb11ac0 100644 --- a/docs/en/api-guides/build-system.rst +++ b/docs/en/api-guides/build-system.rst @@ -1104,24 +1104,24 @@ For the following example, suppose the build target is ``esp32`` and these files .. code-block:: none - sdkconfig.defaults - sdkconfig.defaults.esp32 - sdkconfig_devkit1 + sdkconfig.defaults + sdkconfig.defaults.esp32 + sdkconfig_devkit1 **Example 1**: ``SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig_devkit1"`` The build system will apply the files in this order: -1. ``sdkconfig.defaults`` -2. ``sdkconfig.defaults.esp32`` - build system will always try to load target specific variation of every file listed in ``SDKCONFIG_DEFAULTS`` -3. ``sdkconfig_devkit1`` +1. ``sdkconfig.defaults``. +2. ``sdkconfig.defaults.esp32`` - build system will always try to load target specific variation of every file listed in ``SDKCONFIG_DEFAULTS``. +3. ``sdkconfig_devkit1``. 4. The build system will also attempt to load a file named ``sdkconfig_devkit1.esp32``, but because there is no file with this name, no additional file will be loaded. **Example 2**: ``SDKCONFIG_DEFAULTS="sdkconfig_devkit1"`` The build system will apply the files in this order: -1. ``sdkconfig_devkit1`` +1. ``sdkconfig_devkit1``. 2. The build system will also attempt to load a file named ``sdkconfig_devkit1.esp32``, but because there is no file with this name, no additional file will be loaded. .. warning:: diff --git a/docs/zh_CN/api-guides/build-system.rst b/docs/zh_CN/api-guides/build-system.rst index 415a9d5e0c..65b2f7109e 100644 --- a/docs/zh_CN/api-guides/build-system.rst +++ b/docs/zh_CN/api-guides/build-system.rst @@ -1100,7 +1100,33 @@ ExternalProject 的依赖与构建清理 如果使用 ``SDKCONFIG_DEFAULTS`` 覆盖默认文件的名称，则硬件目标的默认文件名也会从 ``SDKCONFIG_DEFAULTS`` 值中派生。如果 ``SDKCONFIG_DEFAULTS`` 中有多个文件，硬件目标文件会在引入该硬件目标文件的文件之后应用， 而 ``SDKCONFIG_DEFAULTS`` 中所有其它后续文件则会在硬件目标文件之后应用 。 -例如，如果 ``SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig_devkit1"``，并且在同一文件夹中有一个 ``sdkconfig.defaults.esp32`` 文件，那么这些文件将按以下顺序应用：（1) sdkconfig.defaults (2) sdkconfig.defaults.esp32 (3) sdkconfig_devkit1。 +以下示例中，假定构建目标为 ``esp32``，且项目目录中有下列文件： + +.. code-block:: none + + sdkconfig.defaults + sdkconfig.defaults.esp32 + sdkconfig_devkit1 + +**示例 1**： ``SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig_devkit1"`` + +构建系统将按以下顺序应用这些文件： + +1. ``sdkconfig.defaults``。 +2. ``sdkconfig.defaults.esp32`` — 对于 ``SDKCONFIG_DEFAULTS`` 中列出的每个文件，构建系统都会尝试加载其对应目标芯片的变体文件。 +3. ``sdkconfig_devkit1``。 +4. 构建系统还会尝试加载 ``sdkconfig_devkit1.esp32``，但由于项目中不存在以此命名的文件，所以不会加载任何额外的文件。 + +**示例 2**： ``SDKCONFIG_DEFAULTS="sdkconfig_devkit1"`` + +构建系统将按以下顺序应用这些文件： + +1. ``sdkconfig_devkit1``。 +2. 构建系统还会尝试加载 ``sdkconfig_devkit1.esp32``，但由于项目中不存在以此命名的文件，所以不会加载任何额外的文件。 + +.. warning:: + + 在第二个示例中，标准的 ``sdkconfig.defaults`` （或其特定于目标的变体）未被应用，因为它未被显式包含在 ``SDKCONFIG_DEFAULTS`` 中。 关于项目配置的详细信息，请参阅 :ref:`项目配置指南 `。关于配置文件的详细信息，请参阅 :ref:`配置文件的结构和关系 `。