Merge branch 'docs/clarify_sdkconfig_defaults_example_v5.5' into 'release/v5.5'

docs: clarify how SDKCONFIG_DEFAULTS cache variable works (v5.5)

See merge request espressif/esp-idf!47190

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

@@ -1104,7 +1104,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 <project-configuration-guide>`. In the :ref:`Configuration Files Structure and Relationships <configuration-structure>`, you can find lower-level information about the configuration files.
 

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

@@ -1104,7 +1104,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:`项目配置指南 <project-configuration-guide>`。关于配置文件的详细信息，请参阅 :ref:`配置文件的结构和关系 <configuration-structure>`。