Merge branch 'change/add-support-for-kconfig-report_v6.0' into 'release/v6.0'

Change/add support for kconfig report (v6.0)

See merge request espressif/esp-idf!43592

docs/en/api-guides/kconfig/component-configuration-guide.rst

@@ -5,9 +5,10 @@ Component Configuration Guide
 
 This guide is intended to describe how to define configuration options for components in ESP-IDF. Following topics will be covered:
 
-- How to define new configuration options for components.
-- Basic syntax of Kconfig language.
-- How to ensure backward compatibility.
+- How to define new configuration options for components
+- Basic syntax of Kconfig language
+- How to ensure backward compatibility
+- How to suppress certain warnings regarding Kconfig options
 
 How Configuration Works in ESP-IDF
 ----------------------------------
@@ -97,3 +98,33 @@ This behavior is suppressed in ESP-IDF by the the configuration tool (invoked by
 1. Configuration tool searches the whole ESP-IDF folder for ``sdkconfig.rename`` files. If the project target (``<chip>``) matches the last suffix of any ``sdkconfig.rename.<chip>`` file, the file will be used in the next step as well.
 
 2. After collecting all the relevant files, the ``sdkconfig`` file (and ``sdkconfig.h/json/cmake`` files if any) is post-processed. A block of compatibility statements for all the renamed options is added during the post-process to the end of the file(s). The block starts with ``# Deprecated options for backward compatibility`` and ends with ``# End of deprecated options``.
+
+.. _supressing-kconfig-messages:
+
+Suppressing Info/Warning Messages in Kconfig
+--------------------------------------------
+
+In some situations, it may be desirable to suppress specific info or warning messages in the configuration report. The ``# ignore: <ignore-code>`` pragma allows you to do this, where ``<ignore-code>`` refers to the report area of the message in the configuration report (e.g., ``multiple-definition`` ignore code for ``Multiple Symbol/Choice Definitions`` area). Each ignore code has both long and short form.
+
+.. note::
+
+    For more information about report areas or the configuration report, please refer to the :ref:`configuration-report` section of the Project Configuration Guide.
+
+Currently, the following ignore code is supported:
+
+* ``multiple-definition``/``MD``: Suppresses the message for all occurrences of a given configuration option in the ``Multiple Symbol/Choice Definitions`` report area. It is sufficient to place the pragma on just one of the definitions.
+
+Example:
+
+.. code-block:: kconfig
+
+    # Even though the LED_PIN option is defined multiple times, the info message about this will be suppressed
+    config LED_PIN # ignore: multiple-definition
+        int "Pin for LED"
+        default 1
+
+    # (...)
+
+    config LED_PIN # here, the pragma is not needed (but it is allowed)
+        int "Pin for LED"
+        default 3

docs/en/api-guides/kconfig/project-configuration-guide.rst

@@ -8,6 +8,7 @@ This guide is intended to describe three aspects of project configuration in ESP
 - How the configuration can be edited (``idf.py menuconfig`` and configuration via plugins)
 - How to use configuration values in C code and CMake
 - How to define new configuration options for the project
+- What is configuration report and how to understand it
 
 .. _project-configuration-menu:
 
@@ -105,3 +106,82 @@ Defining New Configuration Options for the Project
 
 Some applications can get very complex and require a lot of configuration options. In such cases, it is useful to define new configuration options for the project. Similar to components, the application can have its own configuration options. These options are defined in the  ``Kconfig`` or ``Kconfig.projbuild`` file in the ``main`` folder of the project. The process is the same as :ref:`defining new configuration options for components <component-configuration-guide>`, only with **different location** location of the ``Kconfig`` or ``Kconfig.projbuild`` file (``main`` instead of the root folder).
 
+
+.. _configuration-report:
+
+Configuration Report
+--------------------
+
+The configuration report is a semi-structured text designed to provide a unified overview of the project's configuration issues, if any. The report helps debug configuration-related issues by aggregating all messages, warnings, and errors related to the project's configuration. This report is automatically printed in the console whenever the project configuration is (re)built; typically during the first build of the project or when ``idf.py menuconfig`` command is run.
+
+The configuration report consists of a header with general information (parser version, verbosity, status) and zero or more report areas. Each report area groups together messages related to a specific issue. For a more verbose output, set ``KCONFIG_REPORT_VERBOSITY`` environment variable to ``verbose`` before build or ``idf.py menuconfig`` command.
+
+Example of a configuration report (actual output is colored):
+
+.. code-block:: console
+
+    Configuration report
+    --------------------
+    Parser Version: 1
+    Verbosity: default
+    Status: Finished with notifications
+
+    Multiple Symbol/Choice Definitions
+    ----------------------------------
+
+    SYMBOL_NAME
+        path/to/first/Kconfig_with_definition:line_number
+        path/to/second/Kconfig_with_definition:line_number
+
+    ANOTHER_SYMBOL_NAME
+        another/path/to/first/Kconfig_with_definition:line_number
+        another/path/to/second/Kconfig_with_definition:line_number
+
+How to Generate the Configuration Report in JSON Format
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The configuration report can be generated in JSON format using the ``idf.py config-report`` command. This command will generate a JSON file with the project configuration report in the ``build/config`` directory with the name ``kconfig_parse_report.json``.
+
+.. code-block:: console
+
+    idf.py config-report
+
+.. warning::
+
+    The JSON file structure is in the experimental stage and may change in the future.
+
+The JSON file contains two main sections: ``header`` and ``areas``:
+
+* ``header``: contains the general information about the configuration report: report type, Kconfig parser version, verbosity, status, number of unique symbols, defaults policy.
+* ``areas``: contains the list of report areas. Each area contains errors, warnings and info messages related to the specific area (e.g. configuration options defined in multiple places etc.). The full list of areas is defined in the `esp-idf-kconfig Documentation <https://docs.espressif.com/projects/esp-idf-kconfig/en/latest/kconfiglib/configuration-report.html>`_.
+
+Example of a JSON file:
+
+.. code-block:: json
+
+    {
+        "header": {
+            "report_type": "kconfig",
+            "parser_version": "1",
+            "verbosity": "default",
+            "status": "Finished with notifications",
+            "number_of_unique_symbols": 100,
+            "defaults_policy": "sdkconfig"
+        },
+        "areas": [
+            {
+                "title": "Multiple Symbol/Choice Definitions",
+                "severity": "Info",
+                "data": {
+                    "EXAMPLE_SYMBOL_NAME": [
+                        "path/to/Kconfig:42",
+                        "path/to/another/Kconfig:32"
+                    ]
+                }
+            }
+        ]
+    }
+
+.. note::
+
+    Detailed information about the configuration report can be found in the `esp-idf-kconfig Documentation <https://docs.espressif.com/projects/esp-idf-kconfig/en/latest/kconfiglib/configuration-report.html>`_.

tools/cmake/kconfig.cmake

@@ -194,6 +194,12 @@ function(__kconfig_generate_config sdkconfig sdkconfig_defaults)
         --list-separator=semicolon
         --env-file ${config_env_path})
 
+    set(kconfig_report_verbosity "$ENV{KCONFIG_REPORT_VERBOSITY}")
+    if(NOT kconfig_report_verbosity)
+        set(kconfig_report_verbosity "default")
+        message(STATUS "KCONFIG_REPORT_VERBOSITY not set, using default")
+    endif()
+
     set(kconfgen_basecommand
         ${python} -m kconfgen
         --list-separator=semicolon
@@ -293,6 +299,7 @@ function(__kconfig_generate_config sdkconfig sdkconfig_defaults)
         --env "IDF_TOOLCHAIN=${idf_toolchain}"
         --env "IDF_ENV_FPGA=${idf_env_fpga}"
         --env "IDF_INIT_VERSION=${idf_init_version}"
+        --env "KCONFIG_REPORT_VERBOSITY=quiet"
         --dont-write-deprecated
         --output config ${sdkconfig} # Do NOT regenerate the rest of the config files!
         COMMAND ${TERM_CHECK_CMD}
@@ -315,6 +322,21 @@ function(__kconfig_generate_config sdkconfig sdkconfig_defaults)
         --env "IDF_ENV_FPGA=${idf_env_fpga}"
         --env "IDF_INIT_VERSION=${idf_init_version}"
         ${kconfgen_output_options}
+        --env "KCONFIG_REPORT_VERBOSITY=${kconfig_report_verbosity}"
+        )
+
+    # Custom target to generate configuration report to JSON
+    add_custom_target(config-report
+        COMMAND ${prepare_kconfig_files_command}
+        COMMAND ${kconfgen_basecommand}
+        --env "IDF_TARGET=${idf_target}"
+        --env "IDF_TOOLCHAIN=${idf_toolchain}"
+        --env "IDF_ENV_FPGA=${idf_env_fpga}"
+        --env "IDF_INIT_VERSION=${idf_init_version}"
+        --output report "${config_dir}/kconfig_parse_report.json"
+        --env "KCONFIG_REPORT_VERBOSITY=${kconfig_report_verbosity}"
+        USES_TERMINAL
+        VERBATIM
         )
 
     # Custom target to run kconfserver from the build tool
@@ -325,6 +347,7 @@ function(__kconfig_generate_config sdkconfig sdkconfig_defaults)
         --kconfig ${IDF_PATH}/Kconfig
         --sdkconfig-rename ${root_sdkconfig_rename}
         --config ${sdkconfig}
+        --env "KCONFIG_REPORT_VERBOSITY=${kconfig_report_verbosity}"
         VERBATIM
         USES_TERMINAL)
 
@@ -333,6 +356,7 @@ function(__kconfig_generate_config sdkconfig sdkconfig_defaults)
         COMMAND ${kconfgen_basecommand}
         --dont-write-deprecated
         --output savedefconfig ${CMAKE_SOURCE_DIR}/sdkconfig.defaults
+        --env "KCONFIG_REPORT_VERBOSITY=${kconfig_report_verbosity}"
         USES_TERMINAL
         )
 endfunction()

tools/idf_py_actions/core_ext.py

@@ -80,6 +80,13 @@ def action_extensions(base_actions: dict, project_path: str) -> Any:
             else:
                 raise
 
+    def config_report_target(target_name: str, ctx: Context, args: PropertyDict) -> None:
+        """
+        Generate a JSON file with the project configuration report in the build/config directory.
+        """
+        ensure_build_directory(args, ctx.info_name)
+        run_target(target_name, args)
+
     def size_target(
         target_name: str, ctx: Context, args: PropertyDict, output_format: str, output_file: str, diff_map_file: str
     ) -> None:
@@ -624,6 +631,11 @@ def action_extensions(base_actions: dict, project_path: str) -> Any:
                     }
                 ],
             },
+            'config-report': {
+                'callback': config_report_target,
+                'help': 'Generate a JSON file with the project configuration report in the build directory.',
+                'options': global_options,
+            },
             'size': {
                 'callback': size_target,
                 'help': 'Print basic size information about the app.',