Merge branch 'feat/support_kconfig' into 'main'

feat: support kconfig item as left value in if clause

See merge request espressif/idf-component-manager!477

Author: hfudev

docs/en/reference/manifest_file.rst

@@ -390,35 +390,79 @@ Conditional Dependencies
 
 The ``if`` field is a boolean expression that is evaluated to determine if the dependency should be included. An expression consists of three parts: left value, operator, and right value.
 
-The left value could be
+Here's a detailed comparison table for the ``if`` field:
 
--  keyword ``idf_version``: the version of ESP-IDF that is used to build the component
--  keyword ``target``: the current target selected for the project
--  a string
--  `environment variables`_
+.. list-table:: Supported Comparison Types
+   :header-rows: 1
 
-The right value could be
+   -  -  Left Value Type
+      -  Operators
+      -  Right Value Type
 
--  a string
--  a list of strings
+   -  -  keyword ``idf_version``
+      -  N/A
+      -  string that represents :ref:`version ranges <version-range-specifications>`
 
-The operator to compare with a string could be
+   -  -  keyword ``target``
+      -  ``!=``, ``==``
+      -  string
 
--  ``<=``
--  ``<``
--  ``>=``
--  ``>``
--  ``~=``
--  ``~``
--  ``=``
--  ``^``
--  ``!=``
--  ``==``
+   -  -  keyword ``target``
+      -  ``in``, ``not in``
+      -  list of strings
 
-The operator to compare with a list of strings could be
+   -  -  arbitrary string
+      -  ``!=``, ``==``
+      -  string
 
--  ``not in``
--  ``in``
+   -  -  arbitrary string
+      -  ``in``, ``not in``
+      -  list of strings
+
+   -  -  `environment variables`_
+      -  N/A
+      -  string that represents :ref:`Version Ranges <version-range-specifications>`
+
+   -  -  `environment variables`_
+      -  ``!=``, ``==``
+      -  string
+
+   -  -  `environment variables`_
+      -  ``in``, ``not in``
+      -  list of strings
+
+   -  -  `kconfig options`_
+      -  ``==``, ``!=``
+      -  string
+
+   -  -  `kconfig options`_
+      -  ``in``, ``not in``
+      -  list of strings
+
+   -  -  `kconfig options`_
+      -  ``==``, ``!=``, ``<=``, ``<``, ``>=``, ``>``
+      -  decimal integer or hexadecimal integer (e.g. ``0x1234``)
+
+   -  -  `kconfig options`_
+      -  ``!=``, ``==``
+      -  boolean (``True``, ``False``)
+
+.. versionadded:: 2.2.0
+
+   - Support `kconfig options`_ as left value (requires ESP-IDF v5.5+)
+   - Support ``boolean``, ``integer`` and ``hexadecimal integer`` data types for `kconfig options`_
+
+.. warning::
+
+   Since kconfig supports data types, you MUST use double quotes for strings while comparing with kconfig options. Otherwise, the component manager will treat the value as an integer, and raise an error if the value is not parsable as an integer.
+
+   Double quotes are not required for strings when not comparing with kconfig options, but we recommend using them for consistency.
+
+.. warning::
+
+   If you specified `environment variables`_ as the left value of the if clause, and the environment variable is not set, an error will be raised.
+
+   If you specified `kconfig options`_ as the left value of the if clause, but the kconfig is included in your project, or components, an error will be raised.
 
 To make a complex boolean expression, you can use nested parentheses with boolean operators ``&&`` and ``||``.
 
@@ -429,22 +473,22 @@ To make a complex boolean expression, you can use nested parentheses with boolea
       version: "~1.0.0"
       rules:
         - if: "idf_version >=3.3,<5.0"
-        - if: "target in [esp32, esp32c3]"
+        - if: target in ["esp32", "esp32c3"]
         # the above two conditions equals to
-        - if: idf_version >=3.3,<5.0 && target in [esp32, esp32c3]
+        - if: idf_version >=3.3,<5.0 && target in ["esp32", "esp32c3"]
 
-The left value of the if clause could be `environment variables`_. If the environment variable is not set, an error will be raised.
+.. hint::
 
-One possible use-case is to test it in the CI/CD pipeline. For example:
+   One possible use-case of `environment variables`_ is to test it in the CI/CD pipeline. For example:
 
-.. code:: yaml
+   .. code:: yaml
 
-   dependencies:
-     optional_component:
-       matches:
-         - if: "$TESTING_COMPONENT in [foo, bar]"
+      dependencies:
+        optional_component:
+          matches:
+            - if: "$TESTING_COMPONENT in [foo, bar]"
 
-The dependency will only be included when the environment variable ``TESTING_COMPONENT`` is set to ``foo`` or ``bar``.
+   The dependency will only be included when the environment variable ``TESTING_COMPONENT`` is set to ``foo`` or ``bar``.
 
 ``version`` (if clause)
 -----------------------
@@ -472,6 +516,10 @@ Environment Variables
 
    Environment variables are not allowed in manifests when uploading components to the ESP Component Registry.
 
+.. warning::
+
+   Environment variables should only contain alphanumeric characters and underscores, and should not start with a number.
+
 You can use environment variables for the attributes that support them. The component manager will replace the environment variables with their values. Use the following syntax:
 
 -  ``$VAR``
@@ -481,6 +529,61 @@ If you need to use a literal dollar sign (``$``), escape it with another dollar
 
 .. _local-source:
 
+Kconfig Options
+===============
+
+You can use Kconfig options for the attributes that support them. All Kconfig options are prefixed with ``$kconfig.``, and don't have to include the ``CONFIG_`` prefix.
+
+For example, to compare with the Kconfig option ``CONFIG_MY_OPTION``, use ``$kconfig.MY_OPTION``.
+
+Besides, only Kconfig options that are defined in the ESP-IDF project and the direct dependency components are supported. For example
+
+.. code:: yaml
+
+   dependencies:
+      cmp:
+        version: "*"
+        matches:
+          - if: "$kconfig.BOOTLOADER_LOG_LEVEL_WARN == True"
+
+This works, since ``CONFIG_BOOTLOADER_LOG_LEVEL_WARN`` is defined in the ESP-IDF project.
+
+.. code:: yaml
+
+   dependencies:
+      example/cmp:
+        version: "*"
+        matches:
+          - if: "$kconfig.MY_OPTION == True"
+
+This will not work, since ``CONFIG_MY_OPTION`` is not defined in the ESP-IDF project.
+
+.. code:: yaml
+
+   dependencies:
+      espressif/mdns:
+         version: "1.8.1"
+
+      example/cmp:
+        version: "*"
+        matches:
+          - if: "$kconfig.MDNS_MAX_SERVICES == 10"
+
+This works, since ``CONFIG_MDNS_MAX_SERVICES`` is defined in the ``espressif/mdns`` component, and ``espressif/mdns`` is a direct dependency of your project.
+
+.. code:: yaml
+
+   dependencies:
+      cmp_a:
+         version: "*"
+
+      example/cmp:
+        version: "*"
+        matches:
+          - if: "$kconfig.OPTION_FROM_CMP_B == True"
+
+This will not work, even if ``CONFIG_OPTION_FROM_CMP_B`` is defined in the ``cmp_b`` component, and ``cmp_a`` depends on ``cmp_b``, since `cmp_b` is not a direct dependency of your project.
+
 Local Directory Dependencies
 ============================
 

idf_component_manager/core.py

@@ -25,6 +25,7 @@
 from idf_component_tools.build_system_tools import build_name, is_component
 from idf_component_tools.config import root_managed_components_dir
 from idf_component_tools.constants import MANIFEST_FILENAME
+from idf_component_tools.debugger import KCONFIG_CONTEXT
 from idf_component_tools.errors import (
     FatalError,
     InternalError,
@@ -132,6 +133,7 @@ def __init__(
         lock_path: t.Optional[str] = None,
         manifest_path: t.Optional[str] = None,
         interface_version: int = 0,
+        sdkconfig_json_file: t.Optional[str] = None,
     ) -> None:
         # Working directory
         self.path = Path(path).resolve()
@@ -164,6 +166,9 @@ def __init__(
 
         self.interface_version = interface_version
 
+        if sdkconfig_json_file:
+            KCONFIG_CONTEXT.get().update_from_file(sdkconfig_json_file)
+
     def _get_manifest_dir(self, component: str = 'main', path: t.Optional[str] = None) -> str:
         if component != 'main' and path is not None:
             raise FatalError(
@@ -665,6 +670,7 @@ def prepare_dep_dirs(
         managed_components_list_file,
         component_list_file,
         local_components_list_file=None,
+        sdkconfig_json_file=None,
     ):
         """Process all manifests and download all dependencies"""
         # root core components
@@ -719,7 +725,10 @@ def prepare_dep_dirs(
 
             project_requirements = ProjectRequirements(manifests)
             downloaded_components = download_project_dependencies(
-                project_requirements, self.lock_path, self.managed_components_path
+                project_requirements,
+                self.lock_path,
+                self.managed_components_path,
+                sdkconfig_json_file,
             )
 
         # Exclude requirements paths

idf_component_manager/prepare_components/prepare.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 #
-# SPDX-FileCopyrightText: 2019-2024 Espressif Systems (Shanghai) CO LTD
+# SPDX-FileCopyrightText: 2019-2025 Espressif Systems (Shanghai) CO LTD
 # SPDX-License-Identifier: Apache-2.0
 #
 # 'prepare.py' is a tool to be used by CMake build system to prepare components
@@ -12,6 +12,7 @@
 
 from idf_component_manager.core import ComponentManager
 from idf_component_tools import error, setup_logging
+from idf_component_tools.debugger import KCONFIG_CONTEXT
 from idf_component_tools.errors import FatalError
 
 
@@ -20,6 +21,9 @@ def _component_list_file(build_dir):
 
 
 def prepare_dep_dirs(args):
+    if args.sdkconfig_json_file:
+        KCONFIG_CONTEXT.get().update_from_file(args.sdkconfig_json_file)
+
     build_dir = args.build_dir or os.path.dirname(args.managed_components_list_file)
     ComponentManager(
         args.project_dir,
@@ -31,8 +35,15 @@ def prepare_dep_dirs(args):
         local_components_list_file=args.local_components_list_file,
     )
 
+    kconfig_ctx = KCONFIG_CONTEXT.get()
+    if kconfig_ctx.missed_keys:
+        exit(10)
+
 
 def inject_requirements(args):
+    if args.sdkconfig_json_file:
+        KCONFIG_CONTEXT.get().update_from_file(args.sdkconfig_json_file)
+
     ComponentManager(
         args.project_dir,
         lock_path=args.lock_path,
@@ -58,17 +69,22 @@ def main():
     # *1* starting ESP-IDF 5.0
     # *2* starting ESP-IDF 5.1
     # *3* starting ESP-IDF 5.2
+    # *4* starting ESP-IDF 5.5
 
     parser.add_argument(
         '--interface_version',
         help='Version of ESP-IDF build system integration',
         default=0,
         type=int,
-        choices=[0, 1, 2, 3],
+        choices=[0, 1, 2, 3, 4],
     )
 
     parser.add_argument('--lock_path', help='lock file path relative to the project path')
-
+    parser.add_argument(
+        '--sdkconfig_json_file',
+        required=False,
+        help='Path to file with sdkconfig.json, used for parsing kconfig in if clauses',
+    )
     subparsers = parser.add_subparsers(dest='step')
     subparsers.required = True
 
@@ -109,7 +125,7 @@ def main():
 
     for step in inject_step_data:
         inject_step = subparsers.add_parser(
-            step['name'], help=f"Inject requirements to CMake{step.get('extra_help', '')}"
+            step['name'], help=f'Inject requirements to CMake{step.get("extra_help", "")}'
         )
         inject_step.set_defaults(func=inject_requirements)
         inject_step.add_argument(

idf_component_tools/constants.py

@@ -26,3 +26,5 @@
     {} -m pip install --upgrade idf-component-manager
 """.format(sys.executable)
 MANIFEST_FILENAME = 'idf_component.yml'
+
+KCONFIG_VAR_PREFIX = '$kconfig.'

idf_component_tools/debugger.py

@@ -1,9 +1,14 @@
-# SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+# SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
 # SPDX-License-Identifier: Apache-2.0
 import contextvars
+import json
+import os.path
 import typing as t
 from collections import defaultdict
 
+if t.TYPE_CHECKING:
+    from idf_component_tools.manifest import ComponentRequirement
+
 
 class DebugInfoCollector:
     def __init__(self):
@@ -17,4 +22,21 @@ def declare_dep(self, dep_name: str, introduced_by: str):
         self.dep_introduced_by[dep_name].add(introduced_by)
 
 
+class SdkconfigContext:
+    def __init__(self):
+        self.sdkconfig: t.Dict[str, t.Any] = {}
+        self.missed_keys: t.Dict[str, t.Set['ComponentRequirement']] = defaultdict(set)
+
+    def update_from_file(self, file_path: str):
+        if not os.path.isfile(file_path):
+            return
+
+        with open(file_path, encoding='utf8') as f:
+            self.sdkconfig.update(json.load(f))
+
+    def set_missed_kconfig(self, key: str, req: 'ComponentRequirement'):
+        self.missed_keys[key].add(req)
+
+
 DEBUG_INFO_COLLECTOR = contextvars.ContextVar('DebugInfoCollector', default=DebugInfoCollector())
+KCONFIG_CONTEXT = contextvars.ContextVar('SdkconfigContext', default=SdkconfigContext())

idf_component_tools/errors.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
+# SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD
 # SPDX-License-Identifier: Apache-2.0
 
 
@@ -122,3 +122,8 @@ class WarningAsExceptionError(FatalError):
 
 class NoSuchProfile(FatalError):
     pass
+
+
+# not fatal error, since it shall be caught, and handle exit code
+class MissingKconfigError(Exception):
+    pass