Merge branch 'docs/clarify_renames' into 'master'

docs(kconfig): clarify how multiple renames work in sdkconfig.renames

Closes DOC-14265

See merge request espressif/esp-idf!46749

docs/en/api-guides/kconfig/configuration_structure.rst

@@ -1,13 +1,13 @@
 .. _configuration-structure:
 
-Configuration Files Structure and Relationships
+Configuration File Structure and Relationships
 ===============================================
 
 .. note::
 
-    This article primarily focuses on the structure of the files. For more information about project configuration, please refer to the :ref:`Project Configuration Guide <project-configuration-guide>`. For the component configuration, please refer to the :ref:`Component Configuration Guide <component-configuration-guide>`.
+    This article primarily focuses on the structure of the configuration files. For more information about project configuration, please refer to the :ref:`Project Configuration Guide <project-configuration-guide>`. For the component configuration, please refer to the :ref:`Component Configuration Guide <component-configuration-guide>`.
 
-ESP-IDF uses `Kconfig language <https://docs.espressif.com/projects/esp-idf-kconfig/en/latest/kconfiglib/language.html>`_ for configuration of the project. Configuration consists of config options (e.g. ``CONFIG_IDF_TARGET``) and their values (e.g. ``esp32``). Every config option gets a prefix ``CONFIG_`` when written out to e.g. ``sdkconfig`` file to distinguish it from e.g. environment variables.
+ESP-IDF uses `Kconfig language <https://docs.espressif.com/projects/esp-idf-kconfig/en/latest/kconfiglib/language.html>`_ for configuration of the project. Configuration consists of config options (e.g., ``CONFIG_IDF_TARGET``) and their values (e.g., ``esp32``). Every config option gets a prefix ``CONFIG_`` when written out to a file such as ``sdkconfig``, to distinguish it from other variables (e.g., environment variables).
 
 In context of ESP-IDF, configuration consists of several files, most importantly:
 
@@ -70,7 +70,7 @@ The ``sdkconfig.old`` file is a backup of the previous configuration. It is gene
 sdkconfig.rename and sdkconfig.rename.<chip>
 ----------------------------------------------------
 
-The ``sdkconfig.rename`` files are used by the build system to ensure backward compatibility. These files are created and maintained by component or ESP-IDF developers and application developer should have no need to edit them.
+The ``sdkconfig.rename`` files are used by the build system to ensure backward compatibility. These files are created and maintained by component or ESP-IDF developers and application developers do not need to edit them.
 
 The structure of the ``sdkconfig.rename`` file is as follows:
 
@@ -79,6 +79,8 @@ The structure of the ``sdkconfig.rename`` file is as follows:
     * ``CONFIG_DEPRECATED_NAME CONFIG_NEW_NAME``, where ``CONFIG_DEPRECATED_NAME`` is the old config name which was renamed in a newer ESP-IDF version to ``CONFIG_NEW_NAME``.
     * ``CONFIG_DEPRECATED_NAME !CONFIG_NEW_INVERTED_NAME`` where ``CONFIG_NEW_INVERTED_NAME`` was introduced in a newer ESP-IDF version by Boolean inversion of the logic value of ``CONFIG_DEPRECATED_NAME``.
 
+If there is more than one mapping for the same deprecated option name (i.e. the same deprecated option name is renamed more than once), the last occurrence is used. Configuration system will report this only if configuration report verbosity is set to ``verbose`` (e.g., via ``KCONFIG_REPORT_VERBOSITY`` environment variable).
+
 Primary use case of this file is to ensure backward compatibility when the config name is changed in the newer ESP-IDF version.
 
 Example:
@@ -111,7 +113,7 @@ sdkconfig.defaults and sdkconfig.defaults.<chip>
 
 Kconfig language provides a way to set default values for configs: ``default`` option in ``Kconfig`` files. However, input ``Kconfig`` file may be in a different project, under version control or there is another reason why it would be inconvenient to directly edit it. In this case, ``sdkconfig.defaults`` file can be used. The file structure is the same as ``sdkconfig`` file; on every line, there is a full config name (including the ``CONFIG_`` prefix) and its value. This value has precedence over the default value in the Kconfig file by ``default`` option.
 
-It is also possible to override the default values only for specific target. In this case, you can create ``sdkconfig.defaults.<chip>`` file, where ``<chip>`` is the target name (e.g. ``esp32s2``). In this case, it is mandatory to create the ``sdkconfig.defaults`` file as well, otherwise the ``sdkconfig.defaults.<chip>`` file will be ignored. However, the ``sdkconfig.defaults`` file can be empty.
+It is also possible to override the default values only for specific target. In this case, you can create ``sdkconfig.defaults.<chip>`` file, where ``<chip>`` is the target name (e.g., ``esp32s2``). In this case, it is mandatory to create the ``sdkconfig.defaults`` file as well, otherwise the ``sdkconfig.defaults.<chip>`` file will be ignored. However, the ``sdkconfig.defaults`` file can be empty.
 
 How to generate ``sdkconfig.defaults`` file:
 
@@ -124,14 +126,16 @@ How to generate ``sdkconfig.defaults`` file:
     User-set values from ``sdkconfig`` file have precedence before ``sdkconfig.defaults`` file. In other words, if the user changes value of some config option which is also set in ``sdkconfig.defaults`` file, the value from ``sdkconfig.defaults`` file will be ignored:
 
     ``sdkconfig.defaults``
+
     .. code-block:: kconfig
 
         CONFIG_SUBLIGHT_SPEED=42
 
     ``sdkconfig``
+
     .. code-block:: kconfig
 
-        # user changed the value e.g. in menuconfig -> value from sdkconfig.defaults will be ignored
+        # user changed the value (e.g., in menuconfig) -> value from sdkconfig.defaults will be ignored
         CONFIG_SUBLIGHT_SPEED=10
 
 It is also possible to override the name of this file by setting an environment variable. For information on how to set the custom file name and in which order the files are processed if multiple files with default values are present, please visit :ref:`Custom Sdkconfig Defaults <custom-sdkconfig-defaults>` section of Build System documentation.
@@ -148,13 +152,13 @@ Example:
         default 10
     (...)
 
-``sdkconifg.defaults``:
+``sdkconfig.defaults``:
 
 .. code-block:: text
 
     CONFIG_SUBLIGHT_SPEED=42
 
-When running e.g. ``idf.py menuconfig``, the ``SUBLIGHT_SPEED`` will be set to 42. If the value will be changed in the GUI, the value from the GUI will be used and saved into ``sdkconfig`` file.
+When running a command such as ``idf.py menuconfig``, the ``SUBLIGHT_SPEED`` will be set to 42. If the value is changed in the GUI, the value from the GUI will be used and saved into ``sdkconfig`` file.
 
 sdkconfig.ci
 ^^^^^^^^^^^^

docs/zh_CN/api-guides/kconfig/configuration_structure.rst

@@ -1 +1,166 @@
-.. include:: ../../../en/api-guides/kconfig/configuration_structure.rst
+.. _configuration-structure:
+
+配置文件的结构与关系
+======================================
+
+.. note::
+
+    本文主要关注配置文件的结构。关于项目配置的更多信息，请参考 :ref:`Project Configuration Guide <project-configuration-guide>`。关于组件配置，请参考 :ref:`Component Configuration Guide <component-configuration-guide>`。
+
+ESP-IDF 使用 `Kconfig language <https://docs.espressif.com/projects/esp-idf-kconfig/en/latest/kconfiglib/language.html>`_ 来配置项目。配置由配置选项（例如 ``CONFIG_IDF_TARGET``）及其取值（例如 ``esp32``）组成。每个配置选项在被写入例如 ``sdkconfig`` 文件时都会带上 ``CONFIG_`` 前缀，以便将其与其他变量（例如环境变量）区分开来。
+
+在 ESP-IDF 的上下文中，配置由若干文件构成，其中最重要的是：
+
+- ``Kconfig`` 和 ``Kconfig.projbuild`` 文件，用于定义配置选项及其相互关系，并给出其默认值（如果有）。
+- ``sdkconfig`` 文件，包含当前使用的配置选项取值。
+- ``sdkconfig.defaults`` 文件，包含用户为配置选项定义的默认值。
+- ``sdkconfig.rename`` 文件，包含用于确保向后兼容的 ``OLD_NAME NEW_NAME`` 配对的配置名。该文件主要由组件或 ESP-IDF 开发者使用。
+
+配置文件可分为两组：一组主要用于 **定义** 配置选项，另一组包含这些选项的 **取值**。第一组包括 ``Kconfig``、``Kconfig.projbuild`` 和 ``sdkconfig.rename`` 文件，第二组包括 ``sdkconfig``、``sdkconfig.defaults``、``sdkconfig.h`` 和 ``sdkconfig.cmake`` 文件。下面各节将对所有文件进行说明。
+
+关于 ESP-IDF 中配置系统的更多信息，请参考 :ref:`Configuration Overview <configuration-overview>`。
+
+.. _kconfig-files:
+
+Kconfig 与 Kconfig.projbuild 文件
+-----------------------------------
+
+``Kconfig.*`` 文件存储配置选项及其属性与相互关系，也可能包含这些配置选项的默认值。每个项目都可以有自己的 ``Kconfig`` 和（或） ``Kconfig.projbuild`` 文件，用于为该项目定义配置选项。
+
+``Kconfig`` 与 ``Kconfig.projbuild`` 文件之间唯一的区别在于其内容出现在配置界面 (menuconfig) 中的位置：
+
+- ``Kconfig``：该文件的内容会出现在配置界面的 ``Component config`` 窗口中。
+- ``Kconfig.projbuild``：该文件的内容会出现在配置界面的根窗口中。
+
+``Kconfig`` 文件示例：
+
+.. code-block:: kconfig
+
+    mainmenu "Motors configuration"
+
+        config SUBLIGHT_DRIVE_ENABLED
+            bool "Enable sublight drive"
+            default y
+            help
+                This option enables sublight on our spaceship.
+
+关于 Kconfig 语言的更多信息，请参考 `Kconfig Documentation <https://docs.espressif.com/projects/esp-idf-kconfig/en/latest/kconfiglib/language.html>`_。
+
+.. _sdkconfig-file:
+
+sdkconfig 与 sdkconfig.old
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+在 ``sdkconfig`` 文件中，存储着 **当前分配** 给配置选项的 **取值**。该文件自动生成且不应手动编辑，因为配置选项之间可能存在相互关系（依赖与反向依赖），手动编辑会破坏这些关系。``sdkconfig`` 文件同时包含用户设定值与默认值，因此提供了所有可用配置选项及其当前取值的完整列表。
+
+每一行符合下列模式之一：
+
+- ``CONFIG_NAME=<value>``：配置名及其取值。
+- ``# CONFIG_NAME is not set``：布尔配置 ``CONFIG_NAME`` 可见，但当前值为 n。对于非布尔配置，则会出现 ``CONFIG_NAME=""``。
+- 其他以 # 开头的注释与空行。
+
+``sdkconfig.old`` 文件是之前配置的备份。每次生成 ``sdkconfig`` 文件时都会生成该备份文件。
+
+.. note::
+
+    项目中还包含其他 sdkconfig.* 文件，即 ``sdkconfig.h``、``sdkconfig.cmake``、``sdkconfig.json``。这些文件与上面提到的 ``sdkconfig`` 文件内容相同，但格式不同。它们分别用于对应的工具（C/C++ 代码、CMake）。更多信息可查看 :ref:`configs-in-C-Cmake`。
+
+.. _sdkconfig-rename-file:
+
+sdkconfig.rename 与 sdkconfig.rename.<chip>
+----------------------------------------------------
+
+``sdkconfig.rename`` 文件由构建系统用于确保向后兼容。这些文件由组件或 ESP-IDF 开发者创建并维护，应用开发者一般无需编辑。
+
+``sdkconfig.rename`` 文件的结构如下：
+
+* 以 ``#`` 开头的行和空行会被忽略。
+* 其他所有行应符合以下格式之一：
+    * ``CONFIG_DEPRECATED_NAME CONFIG_NEW_NAME``，其中 ``CONFIG_DEPRECATED_NAME`` 是旧版配置项名称，在较新版本的 ESP-IDF 中已被重命名为 ``CONFIG_NEW_NAME``。
+    * ``CONFIG_DEPRECATED_NAME !CONFIG_NEW_INVERTED_NAME``，其中 ``CONFIG_NEW_INVERTED_NAME`` 是在较新版本的 ESP-IDF 中引入的配置项，其值由 ``CONFIG_DEPRECATED_NAME`` 的逻辑值取反得到。
+
+如果同一弃用选项名存在多个映射（即同一弃用选项名被多次重命名），则以最后一次出现的映射为准。只有将配置报告详细级别设置为 ``verbose`` （例如通过 ``KCONFIG_REPORT_VERBOSITY`` 环境变量）时，配置系统才会报告该情况。
+
+该文件的主要用途是在较新的 ESP-IDF 版本更改配置名时，确保向后兼容。
+
+示例：
+
+``sdkconfig.rename``：
+
+.. code-block:: kconfig
+
+    # 旧名称            新名称
+    CONFIG_WARP_DRIVE     CONFIG_HYPERDRIVE
+    CONFIG_ENABLE_WARP_DRIVE !CONFIG_DISABLE_HYPERDRIVE
+
+``sdkconfig``：
+
+.. code-block:: kconfig
+
+    (...)
+    CONFIG_HYPERDRIVE=y
+    CONFIG_DISABLE_HYPERDRIVE=n
+    (...)
+    # 为向后兼容而保留的弃用选项
+    CONFIG_WARP_DRIVE=y
+    CONFIG_ENABLE_WARP_DRIVE=y
+    # 弃用选项结束
+
+.. _sdkconfig-defaults-file:
+
+sdkconfig.defaults 与 sdkconfig.defaults.<chip>
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Kconfig 语言提供了为配置设置默认值的方式：在 ``Kconfig`` 文件中使用 ``default`` 选项。然而，输入的 ``Kconfig`` 文件可能位于不同的项目中、处于版本控制之下，或出于其他原因不便直接编辑。在这种情况下，可以使用 ``sdkconfig.defaults`` 文件。该文件的结构与 ``sdkconfig`` 文件相同；每一行都是完整的配置名（包含 ``CONFIG_`` 前缀）及其取值。通过 ``default`` 选项设置的默认值会被此处的取值覆盖。
+
+也可以只对特定目标覆盖默认值。在这种情况下，可以创建 ``sdkconfig.defaults.<chip>`` 文件，其中 ``<chip>`` 为目标名称（例如 ``esp32s2``）。此时也必须同时提供 ``sdkconfig.defaults`` 文件，否则 ``sdkconfig.defaults.<chip>`` 文件会被忽略。不过，``sdkconfig.defaults`` 文件可以为空。
+
+如何生成 ``sdkconfig.defaults`` 文件：
+
+1. ``cd`` 进入项目文件夹。
+2. 在 ``idf.py menuconfig`` 中完成所需配置。
+3. 运行 ``idf.py save-defconfig``。这将生成 ``sdkconfig.defaults`` 文件，内容为所有与默认值不同的取值。
+
+.. note::
+
+    ``sdkconfig`` 文件中的用户设定值优先于 ``sdkconfig.defaults`` 文件。换言之，如果用户更改了某个同样在 ``sdkconfig.defaults`` 文件中设置过的配置选项取值，则会忽略 ``sdkconfig.defaults`` 文件中的取值：
+
+    ``sdkconfig.defaults``
+
+    .. code-block:: kconfig
+
+        CONFIG_SUBLIGHT_SPEED=42
+
+    ``sdkconfig``
+
+    .. code-block:: kconfig
+
+        # 用户更改了该值（例如通过 menuconfig 修改） -> 将忽略来自 sdkconfig.defaults 的取值
+        CONFIG_SUBLIGHT_SPEED=10
+
+也可以通过设置环境变量来覆盖该文件名。关于如何自定义文件名，以及当存在多个默认值文件时的处理顺序，请参阅构建系统文档中的 :ref:`Custom Sdkconfig Defaults <custom-sdkconfig-defaults>` 章节。
+
+示例：
+
+``Kconfig``：
+
+.. code-block:: kconfig
+
+    (...)
+    config SUBLIGHT_SPEED
+        int "Sublight speed"
+        default 10
+    (...)
+
+``sdkconfig.defaults``：
+
+.. code-block:: text
+
+    CONFIG_SUBLIGHT_SPEED=42
+
+当运行 ``idf.py menuconfig`` 等命令时，``SUBLIGHT_SPEED`` 将被设置为 42。如果在图形界面中更改了该值，则会使用图形界面中的值并将其保存到 ``sdkconfig`` 文件中。
+
+sdkconfig.ci
+^^^^^^^^^^^^
+
+部分 IDF 示例包含 ``sdkconfig.ci`` 文件。它是持续集成 (CI) 测试框架的一部分，在正常构建过程中会被忽略。