idf-build-apps 2.5.0rc0__tar.gz → 2.5.0rc1__tar.gz

{idf_build_apps-2.5.0rc0 → idf_build_apps-2.5.0rc1}/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file.
 
+## v2.5.0rc1 (2024-09-17)
+
+### Fix
+
+- build_arguments expand @p placeholders
+
+### Refactor
+
+- rename BuildArguments.ignore_warning_strings to ignore_warning_strs
+
 ## v2.5.0rc0 (2024-09-10)
 
 ### Feat

{idf_build_apps-2.5.0rc0 → idf_build_apps-2.5.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: idf-build-apps
-Version: 2.5.0rc0
+Version: 2.5.0rc1
 Summary: Tools for building ESP-IDF related apps.
 Author-email: Fu Hanxi <fuhanxi@espressif.com>
 Requires-Python: >=3.7

{idf_build_apps-2.5.0rc0 → idf_build_apps-2.5.0rc1}/docs/en/references/config_file.md

@@ -1,4 +1,4 @@
-# Configuration File `.idf-build-apps.toml`
+# Configuration File `.idf_build_apps.toml`
 
 There are many CLI options available for `idf-build-apps`. While these options provide usage flexibility, they also make the CLI command too long and difficult to read. However, a configuration file allows defining all these options in a more readable and maintainable way.
 

idf_build_apps-2.5.0rc1/docs/en/references/manifest.rst

@@ -0,0 +1,281 @@
+#########################################
+ Manifest File ``.build-test-rules.yml``
+#########################################
+
+A ``.build-test-rules.yml`` file is the manifest file to control whether the app will be built or tested under the rules.
+
+One typical manifest file look like this:
+
+.. code:: yaml
+
+   [folder]:
+     enable:
+       - if: [if clause]
+         temporary: true  # optional, default to false. `reason` is required if `temporary` is true
+         reason: [your reason]  # optional
+       - ...
+     disable:
+       - if: [if clause]
+       - ...
+     disable_test:
+       - if: [if clause]
+       - ...
+
+*******
+ Terms
+*******
+
+Supported Targets
+=================
+
+This refers to the targets that are fully supported by the ESP-IDF project. You may check the supported targets by running ``idf.py --list-targets``.
+
+``idf-build-apps`` will get this information dynamically from your ``$IDF_PATH``. For ESP-IDF release 5.3, the supported targets are:
+
+-  esp32
+-  esp32s2
+-  esp32c3
+-  esp32s3
+-  esp32c2
+-  esp32c6
+-  esp32h2
+-  esp32p4
+
+Preview Targets
+===============
+
+This refers to the targets that are still in preview status. You may check the preview targets by running ``idf.py --list-targets --preview``.
+
+``idf-build-apps`` will get this information dynamically from your ``$IDF_PATH``. For ESP-IDF release 5.3, the preview targets are:
+
+-  linux
+-  esp32c5
+-  esp32c61
+
+****************
+ ``if`` Clauses
+****************
+
+Operands
+========
+
+-  Capitalized Words
+
+   -  Variables defined in ``IDF_PATH/components/soc/[TARGET]/include/soc/*_caps.h`` or in ``IDF_PATH/components/esp_rom/[TARGET]/*_caps.h``. e.g., ``SOC_WIFI_SUPPORTED``, ``ESP_ROM_HAS_SPI_FLASH``
+   -  ``IDF_TARGET``
+   -  ``IDF_VERSION`` (IDF_VERSION_MAJOR.IDF_VERSION_MINOR.IDF_VERSION_PATCH. e.g., 5.2.0. Will convert to Version object to do a version comparison instead of a string comparison)
+   -  ``IDF_VERSION_MAJOR``
+   -  ``IDF_VERSION_MINOR``
+   -  ``IDF_VERSION_PATCH``
+   -  ``INCLUDE_DEFAULT`` (The default value of supported targets is 1, and the default value of preview targets is 0)
+   -  ``CONFIG_NAME`` (config name defined in :doc:`../explanations/config_rules`)
+   -  environment variables, default to ``0`` if not set
+
+-  String, must be double-quoted. e.g., ``"esp32"``, ``"12345"``
+
+-  Integer, support decimal and hex. e.g., ``1``, ``0xAB``
+
+-  List of strings or integers, or both types at the same time. e.g., ``["esp32", 1]``
+
+Operators
+=========
+
+-  ``==``, ``!=``, ``>``, ``>=``, ``<``, ``<=``
+-  ``and``, ``or``
+-  ``in``, ``not in`` with list
+-  parentheses
+
+Limitations
+===========
+
+All operators are binary operators. For more than two operands, you may use the nested parentheses trick. For example:
+
+-  ``A == 1 or (B == 2 and C in [1,2,3])``
+-  ``(A == 1 and B == 2) or (C not in ["3", "4", 5])``
+
+.. warning::
+
+   Chained ``and`` and ``or`` operators are not supported. The operands start from the third one will be ignored.
+
+   For example, ``A == 1 and B == 2 and C == 3`` will be interpreted as ``A == 1 and B == 2``.
+
+**********************
+ Enable/Disable Rules
+**********************
+
+By default, we enable build and test for all supported targets. In other words, all preview targets are disabled.
+
+To simplify the manifest file, if an app needs to be build and tested on all supported targets, it does not need to be added in a manifest file. The manifest files are files that set the violation rules for apps.
+
+Three rules (disable rules are calculated after the enable rules):
+
+-  ``enable``: run CI build/test jobs for targets that match any of the specified conditions only
+-  ``disable``: will not run CI build/test jobs for targets that match any of the specified conditions
+-  ``disable_test``: will not run CI test jobs for targets that match any of the specified conditions
+
+Each key is a folder. The rule will recursively apply to all apps inside.
+
+Overrides Rules
+===============
+
+If one sub folder is in a special case, you can overwrite the rules for this folder by adding another entry for this folder itself. Each folder’s rules are standalone, and will not inherit its parent’s rules. (YAML inheritance is too complicated for reading)
+
+For example, in the following code block, only ``disable`` rule exists in ``examples/foo/bar``. It’s unaware of its parent’s ``enable`` rule.
+
+.. code:: yaml
+
+   examples/foo:
+     enable:
+       - if: IDF_TARGET == "esp32"
+
+   examples/foo/bar:
+     disable:
+       - if: IDF_TARGET == "esp32s2"
+
+*******************
+ Practical Example
+*******************
+
+Here’s a practical example:
+
+.. code:: yaml
+
+   examples/foo:
+     enable:
+       - if IDF_TARGET in ["esp32", 1, 2, 3]
+       - if IDF_TARGET not in ["4", "5", 6]
+     # should be run under all targets!
+
+   examples/bluetooth:
+     disable:  # disable both build and tests jobs
+       - if: SOC_BT_SUPPORTED != 1
+       # reason is optional if there's no `temporary: true`
+     disable_test:
+       - if: IDF_TARGET == "esp32"
+         temporary: true
+         reason: lack of ci runners  # required when `temporary: true`
+
+   examples/bluetooth/test_foo:
+     # each folder's settings are standalone
+     disable:
+       - if: IDF_TARGET == "esp32s2"
+         temporary: true
+         reason: no idea
+     # unlike examples/bluetooth, the apps under this folder would not be build nor test for "no idea" under target esp32s2
+
+   examples/get-started/hello_world:
+     enable:
+       - if: IDF_TARGET == "linux"
+         reason: this one only supports linux!
+
+   examples/get-started/blink:
+     enable:
+       - if: INCLUDE_DEFAULT == 1 or IDF_TARGET == "linux"
+         reason: This one supports all supported targets and linux
+
+**********************
+ Enhanced YAML Syntax
+**********************
+
+Switch-Like Clauses
+===================
+
+The Switch-Like clauses are supported by two keywords in the YAML file: ``depends_components`` and ``depends_filepatterns``.
+
+Operands
+--------
+
+Switch cases have two main components: the ``if`` clause and the ``default`` clause. Just like a switch statement in c language, The first matched ``if`` clause will be applied. If no ``if`` clause matched, the ``default`` clause will be applied. Here’s an example:
+
+.. code:: yaml
+
+   test1:
+     depends_components:
+       - if: IDF_VERSION == "{IDF_VERSION}"
+         content: [ "component_1" ]
+       - if: CONFIG_NAME == "AWESOME_CONFIG"
+         content: [ "component_2" ]
+       - default: [ "component_3", "component_4" ]
+
+``default`` clause is optional. If you don’t specify any ``default`` clause, it will return an empty array.
+
+Limitations
+-----------
+
+You cannot combine a list and a switch in one node.
+
+Reuse Lists
+===========
+
+To reuse the items defined in a list, you can use the ``+`` and ``-`` postfixes respectively. The order of calculation is always ``+`` first, followed by ``-``.
+
+Array Elements as Strings
+-------------------------
+
+The following YAML code demonstrates how to reuse the elements from a list of strings:
+
+.. code:: yaml
+
+   .base_depends_components: &base-depends-components
+     depends_components:
+       - esp_hw_support
+       - esp_rom
+       - esp_wifi
+
+   examples/wifi/coexist:
+     <<: *base-depends-components
+     depends_components+:
+       - esp_coex
+     depends_components-:
+       - esp_rom
+
+After interpretation, the resulting YAML will be:
+
+.. code:: yaml
+
+   examples/wifi/coexist:
+     depends_components:
+       - esp_hw_support
+       - esp_wifi
+       - esp_coex
+
+This means that the ``esp_rom`` element is removed, and the ``esp_coex`` element is added to the ``depends_components`` list.
+
+Array Elements as Dictionaries
+------------------------------
+
+In addition to reuse elements from a list of strings, you can also perform these operations on a list of dictionaries. The matching is done based on the ``if`` key. Here’s an example:
+
+.. code:: yaml
+
+   .base: &base
+     enable:
+       - if: IDF_VERSION == "5.2.0"
+       - if: IDF_VERSION == "5.3.0"
+
+   foo:
+     <<: *base
+     enable+:
+       # this if statement dictionary will override the one defined in `&base`
+       - if: IDF_VERSION == "5.2.0"
+         temp: true
+       - if: IDF_VERSION == "5.4.0"
+         reason: bar
+
+After interpretation, the resulting YAML will be:
+
+.. code:: yaml
+
+   foo:
+     enable:
+     - if: IDF_VERSION == "5.3.0"
+     - if: IDF_VERSION == "5.2.0"
+       temp: true
+     - if: IDF_VERSION == "5.4.0"
+       reason: bar
+
+In this case, the ``enable`` list is extended with the new ``if`` statement and ``reason`` dictionary.
+
+It’s important to note that the ``if`` dictionary defined in the ``+`` postfix will override the earlier one when the ``if`` statement matches.
+
+This demonstrates how you can use the ``+`` and ``-`` postfixes to extend and remove elements from both string and dictionary lists in our YAML.

{idf_build_apps-2.5.0rc0 → idf_build_apps-2.5.0rc1}/idf_build_apps/__init__.py

@@ -8,7 +8,7 @@ Tools for building ESP-IDF related apps.
 # ruff: noqa: E402
 # avoid circular imports
 
-__version__ = '2.5.0rc0'
+__version__ = '2.5.0rc1'
 
 from .session_args import (
     SessionArgs,

{idf_build_apps-2.5.0rc0 → idf_build_apps-2.5.0rc1}/idf_build_apps/app.py

@@ -74,7 +74,6 @@ class App(BaseModel):
     NAME_PLACEHOLDER: t.ClassVar[str] = '@n'  # replace it with self.name
     FULL_NAME_PLACEHOLDER: t.ClassVar[str] = '@f'  # replace it with escaped self.app_dir
     IDF_VERSION_PLACEHOLDER: t.ClassVar[str] = '@v'  # replace it with the IDF version
-    PARALLEL_INDEX_PLACEHOLDER: t.ClassVar[str] = '@p'  # replace it with the parallel index
     INDEX_PLACEHOLDER: t.ClassVar[str] = '@i'  # replace it with the build index (while build_apps)
 
     SDKCONFIG_LINE_REGEX: t.ClassVar[t.Pattern] = re.compile(r'^([^=]+)=\"?([^\"\n]*)\"?\n*$')
@@ -115,7 +114,6 @@ class App(BaseModel):
     copy_sdkconfig: bool = False
 
     # build_apps() related
-    parallel_index: t.Optional[int] = None  # used for expand
     index: t.Optional[int] = None
 
     # build status related
@@ -244,8 +242,6 @@ class App(BaseModel):
 
         if self.index is not None:
             path = path.replace(self.INDEX_PLACEHOLDER, str(self.index))
-        if self.parallel_index:
-            path = path.replace(self.PARALLEL_INDEX_PLACEHOLDER, str(self.parallel_index))
         path = path.replace(
             self.IDF_VERSION_PLACEHOLDER, f'{IDF_VERSION_MAJOR}_{IDF_VERSION_MINOR}_{IDF_VERSION_PATCH}'
         )

{idf_build_apps-2.5.0rc0 → idf_build_apps-2.5.0rc1}/idf_build_apps/args.py

@@ -760,22 +760,24 @@ class BuildArguments(FindBuildArguments):
         default=None,
         metadata=asdict(
             FieldMetadata(
-                description='[INTERNAL CI USE] record size json filepath of the built apps to the specified file. '
+                description='Record size json filepath of the built apps to the specified file. '
                 'Each line is a json string. Can expand placeholders @p',
             )
         ),
     )
+    _collect_size_info: t.Optional[str] = field(init=False, repr=False, default=None)
     collect_app_info: t.Optional[str] = field(
         default=None,
         metadata=asdict(
             FieldMetadata(
-                description='[INTERNAL CI USE] record serialized app model of the built apps to the specified file. '
+                description='Record serialized app model of the built apps to the specified file. '
                 'Each line is a json string. Can expand placeholders @p',
             )
         ),
     )
+    _collect_app_info: t.Optional[str] = field(init=False, repr=False, default=None)
     ignore_warning_str: InitVar[t.Optional[t.List[str]]] = _Field.UNSET
-    ignore_warning_strings: t.Optional[t.List[str]] = field(
+    ignore_warning_strs: t.Optional[t.List[str]] = field(
         default=None,
         metadata=asdict(
             FieldMetadata(
@@ -816,6 +818,10 @@ class BuildArguments(FindBuildArguments):
             )
         ),
     )
+    _junitxml: t.Optional[str] = field(init=False, repr=False, default=None)
+
+    # used for expanding placeholders
+    PARALLEL_INDEX_PLACEHOLDER: t.ClassVar[str] = '@p'  # replace it with the parallel index
 
     def __post_init__(  # type: ignore
         self,
@@ -841,20 +847,71 @@ class BuildArguments(FindBuildArguments):
             config_rules_str=config_rules_str,
         )
 
-        self.set_deprecated_field('ignore_warning_strings', 'ignore_warning_str', ignore_warning_str)
+        self.set_deprecated_field('ignore_warning_strs', 'ignore_warning_str', ignore_warning_str)
         self.set_deprecated_field('ignore_warning_files', 'ignore_warning_file', ignore_warning_file)
 
-        self.ignore_warning_strings = to_list(self.ignore_warning_strings) or []
+        self.ignore_warning_strs = to_list(self.ignore_warning_strs) or []
 
         ignore_warnings_regexes = []
-        if self.ignore_warning_strings:
-            for s in self.ignore_warning_strings:
+        if self.ignore_warning_strs:
+            for s in self.ignore_warning_strs:
                 ignore_warnings_regexes.append(re.compile(s))
         if self.ignore_warning_files:
             for s in self.ignore_warning_files:
                 ignore_warnings_regexes.append(re.compile(s.strip()))
         App.IGNORE_WARNS_REGEXES = ignore_warnings_regexes
 
+        if not isinstance(BuildArguments.collect_size_info, property):
+            self._collect_size_info = self.collect_size_info
+            BuildArguments.collect_size_info = property(  # type: ignore
+                BuildArguments._get_collect_size_info,
+                BuildArguments._set_collect_size_info,
+            )
+
+        if not isinstance(BuildArguments.collect_app_info, property):
+            self._collect_app_info = self.collect_app_info
+            BuildArguments.collect_app_info = property(  # type: ignore
+                BuildArguments._get_collect_app_info,
+                BuildArguments._set_collect_app_info,
+            )
+
+        if not isinstance(BuildArguments.junitxml, property):
+            self._junitxml = self.junitxml
+            BuildArguments.junitxml = property(  # type: ignore
+                BuildArguments._get_junitxml,
+                BuildArguments._set_junitxml,
+            )
+
+    def _get_collect_size_info(self) -> t.Optional[str]:
+        return (
+            self._collect_size_info.replace(self.PARALLEL_INDEX_PLACEHOLDER, str(self.parallel_index))
+            if self._collect_size_info
+            else None
+        )
+
+    def _set_collect_size_info(self, k: str) -> None:
+        self._collect_size_info = k
+
+    def _get_collect_app_info(self) -> t.Optional[str]:
+        return (
+            self._collect_app_info.replace(self.PARALLEL_INDEX_PLACEHOLDER, str(self.parallel_index))
+            if self._collect_app_info
+            else None
+        )
+
+    def _set_collect_app_info(self, k: str) -> None:
+        self._collect_app_info = k
+
+    def _get_junitxml(self) -> t.Optional[str]:
+        return (
+            self._junitxml.replace(self.PARALLEL_INDEX_PLACEHOLDER, str(self.parallel_index))
+            if self._junitxml
+            else None
+        )
+
+    def _set_junitxml(self, k: str) -> None:
+        self._junitxml = k
+
 
 @dataclass
 class DumpManifestShaArguments(GlobalArguments):

{idf_build_apps-2.5.0rc0 → idf_build_apps-2.5.0rc1}/idf_build_apps/main.py

@@ -125,9 +125,6 @@ def build_apps(
     start, stop = get_parallel_start_stop(len(apps), build_arguments.parallel_count, build_arguments.parallel_index)
     LOGGER.info('Total %s apps. running build for app %s-%s', len(apps), start, stop)
 
-    for app in apps[start - 1 : stop]:  # we use 1-based
-        app.parallel_index = build_arguments.parallel_index
-
     # cleanup collect files if exists at this early-stage
     for f in (build_arguments.collect_app_info, build_arguments.collect_size_info, build_arguments.junitxml):
         if f and os.path.isfile(f):

{idf_build_apps-2.5.0rc0 → idf_build_apps-2.5.0rc1}/pyproject.toml

@@ -59,7 +59,7 @@ idf-build-apps = "idf_build_apps:main.main"
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "2.5.0rc0"
+version = "2.5.0rc1"
 tag_format = "v$version"
 version_files = [
     "idf_build_apps/__init__.py",

{idf_build_apps-2.5.0rc0 → idf_build_apps-2.5.0rc1}/setup.py

@@ -29,7 +29,7 @@ entry_points = \
 {'console_scripts': ['idf-build-apps = idf_build_apps:main.main']}
 
 setup(name='idf-build-apps',
-      version='2.5.0rc0',
+      version='2.5.0rc1',
       description='Tools for building ESP-IDF related apps.',
       author=None,
       author_email='Fu Hanxi <fuhanxi@espressif.com>',

{idf_build_apps-2.5.0rc0 → idf_build_apps-2.5.0rc1}/tests/test_args.py

@@ -2,7 +2,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 
-from idf_build_apps.args import DependencyDrivenBuildArguments, FindArguments, FindBuildArguments
+from idf_build_apps.args import BuildArguments, DependencyDrivenBuildArguments, FindArguments, FindBuildArguments
 from idf_build_apps.config import IDF_BUILD_APPS_TOML_FN
 
 
@@ -38,7 +38,7 @@ def test_init_attr_override(capsys):
     assert (
         'Field `config` is deprecated. Will be removed in the next major release. ' 'Use field `config_rules` instead'
     ) in err_list[0]
-    assert ('Field `config_rules` is already set. Ignoring deprecated field `config`') in err_list[1]
+    assert 'Field `config_rules` is already set. Ignoring deprecated field `config`' in err_list[1]
     assert (
         'Field `config_rules_str` is deprecated. Will be removed in the next major release. '
         'Use field `config_rules` instead'
@@ -64,3 +64,19 @@ no_color = true
 def test_empty_argument():
     args = FindArguments()
     assert args.config_rules is None
+
+
+def test_build_args_expansion():
+    args = BuildArguments(parallel_index=2)
+
+    args.collect_app_info = '@p.txt'
+    assert args.collect_app_info == '2.txt'
+
+    args.parallel_index = 3
+    assert args.collect_app_info == '3.txt'
+
+    args.junitxml = 'x_@p.txt'
+    assert args.junitxml == 'x_3.txt'
+
+    args.collect_size_info = '@p_@p.txt'
+    assert args.collect_size_info == '3_3.txt'

idf_build_apps-2.5.0rc0/docs/en/references/manifest.md

@@ -1,245 +0,0 @@
-# Manifest File `.build-test-rules.yml`
-
-A `.build-test-rules.yml` file is the manifest file to control whether the app will be built or tested under the rules.
-
-One typical manifest file look like this:
-
-```yaml
-[folder]:
-  enable:
-    - if: [if clause]
-      temporary: true  # optional, default to false. `reason` is required if `temporary` is true
-      reason: [your reason]  # optional
-    - ...
-  disable:
-    - if: [if clause]
-    - ...
-  disable_test:
-    - if: [if clause]
-    - ...
-```
-
-## Terms
-
-### Supported Targets
-
-This refers to the targets that are fully supported by the ESP-IDF project. You may check the supported targets by running `idf.py --list-targets`.
-
-`idf-build-apps` will get this information dynamically from your `$IDF_PATH`. For ESP-IDF release 5.3, the supported targets are:
-
-- esp32
-- esp32s2
-- esp32c3
-- esp32s3
-- esp32c2
-- esp32c6
-- esp32h2
-- esp32p4
-
-### Preview Targets
-
-This refers to the targets that are still in preview status. You may check the preview targets by running `idf.py --list-targets --preview`.
-
-`idf-build-apps` will get this information dynamically from your `$IDF_PATH`. For ESP-IDF release 5.3, the preview targets are:
-
-- linux
-- esp32c5
-- esp32c61
-
-## `if` Clauses
-
-### Operands
-
-- Capitalized Words
-  - Variables defined in `IDF_PATH/components/soc/[TARGET]/include/soc/*_caps.h` or in `IDF_PATH/components/esp_rom/[TARGET]/*_caps.h`. e.g., `SOC_WIFI_SUPPORTED`, `ESP_ROM_HAS_SPI_FLASH`
-  - `IDF_TARGET`
-  - `IDF_VERSION` (IDF_VERSION_MAJOR.IDF_VERSION_MINOR.IDF_VERSION_PATCH. e.g., 5.2.0. Will convert to Version object to do a version comparison instead of a string comparison)
-  - `IDF_VERSION_MAJOR`
-  - `IDF_VERSION_MINOR`
-  - `IDF_VERSION_PATCH`
-  - `INCLUDE_DEFAULT` (The default value of supported targets is 1, and the default value of preview targets is 0)
-  - `CONFIG_NAME` (config name defined in [](project:#config-rules))
-  - environment variables, default to `0` if not set
-- String, must be double-quoted. e.g., `"esp32"`, `"12345"`
-- Integer, support decimal and hex. e.g., `1`, `0xAB`
-- List of strings or integers, or both types at the same time. e.g., `["esp32", 1]`
-
-### Operators
-
-- `==`, `!=`, `>`, `>=`, `<`, `<=`
-- `and`, `or`
-- `in`, `not in` with list
-- parentheses
-
-### Limitations
-
-All operators are binary operators. For more than two operands, you may use the nested parentheses trick. For example:
-
-- `A == 1 or (B == 2 and C in [1,2,3])`
-- `(A == 1 and B == 2) or (C not in ["3", "4", 5])`
-
-## Enable/Disable Rules
-
-By default, we enable build and test for all supported targets. In other words, all preview targets are disabled.
-
-To simplify the manifest file, if an app needs to be build and tested on all supported targets, it does not need to be added in a manifest file. The manifest files are files that set the violation rules for apps.
-
-Three rules (disable rules are calculated after the `enable` rule):
-- `enable`: run CI build/test jobs for targets that match any of the specified conditions only
-- `disable`: will not run CI build/test jobs for targets that match any of the specified conditions
-- `disable_test`: will not run CI test jobs for targets that match any of the specified conditions
-
-Each key is a folder. The rule will recursively apply to all apps inside.
-
-### Overrides Rules
-
-If one sub folder is in a special case, you can overwrite the rules for this folder by adding another entry for this folder itself. Each folder's rules are standalone, and will not inherit its parent's rules. (YAML inheritance is too complicated for reading)
-
-For example, in the following code block, only `disable` rule exists in `examples/foo/bar`. It's unaware of its parent's `enable` rule.
-
-```yaml
-examples/foo:
-  enable:
-    - if: IDF_TARGET == "esp32"
-
-examples/foo/bar:
-  disable:
-    - if: IDF_TARGET == "esp32s2"
-```
-
-## Practical Example
-
-Here's a practical example:
-
-```yaml
-examples/foo:
-  enable:
-    - if IDF_TARGET in ["esp32", 1, 2, 3]
-    - if IDF_TARGET not in ["4", "5", 6]
-  # should be run under all targets!
-
-examples/bluetooth:
-  disable:  # disable both build and tests jobs
-    - if: SOC_BT_SUPPORTED != 1
-    # reason is optional if there's no `temporary: true`
-  disable_test:
-    - if: IDF_TARGET == "esp32"
-      temporary: true
-      reason: lack of ci runners  # required when `temporary: true`
-
-examples/bluetooth/test_foo:
-  # each folder's settings are standalone
-  disable:
-    - if: IDF_TARGET == "esp32s2"
-      temporary: true
-      reason: no idea
-  # unlike examples/bluetooth, the apps under this folder would not be build nor test for "no idea" under target esp32s2
-
-examples/get-started/hello_world:
-  enable:
-    - if: IDF_TARGET == "linux"
-      reason: this one only supports linux!
-
-examples/get-started/blink:
-  enable:
-    - if: INCLUDE_DEFAULT == 1 or IDF_TARGET == "linux"
-      reason: This one supports all supported targets and linux
-```
-
-## Enhanced YAML Syntax
-
-### Switch-Like Clauses
-
-The Switch-Like clauses are supported by two keywords in the YAML file: `depends_components` and `depends_filepatterns`.
-
-#### Operands
-
-Switch cases have two main components: the `if` clause and the `default` clause. Just like a switch statement in c language, The first matched `if` clause will be applied. If no `if` clause matched, the `default` clause will be applied. Here's an example:
-
-```yaml
-test1:
-  depends_components:
-    - if: IDF_VERSION == "{IDF_VERSION}"
-      content: [ "component_1" ]
-    - if: CONFIG_NAME == "AWESOME_CONFIG"
-      content: [ "component_2" ]
-    - default: [ "component_3", "component_4" ]
-```
-
-`default` clause is optional. If you don't specify any `default` clause, it will return an empty array.
-
-#### Limitations
-
-You cannot combine a list and a switch in one node.
-
-### Reuse Lists
-
-To reuse the items defined in a list, you can use the `+` and `-` postfixes respectively. The order of calculation is always `+` first, followed by `-`.
-
-#### Array Elements as Strings
-
-The following YAML code demonstrates how to reuse the elements from a list of strings:
-
-```yaml
-.base_depends_components: &base-depends-components
-  depends_components:
-    - esp_hw_support
-    - esp_rom
-    - esp_wifi
-
-examples/wifi/coexist:
-  <<: *base-depends-components
-  depends_components+:
-    - esp_coex
-  depends_components-:
-    - esp_rom
-```
-
-After interpretation, the resulting YAML will be:
-
-```yaml
-examples/wifi/coexist:
-  depends_components:
-    - esp_hw_support
-    - esp_wifi
-    - esp_coex
-```
-
-This means that the `esp_rom` element is removed, and the `esp_coex` element is added to the `depends_components` list.
-
-#### Array Elements as Dictionaries
-
-In addition to reuse elements from a list of strings, you can also perform these operations on a list of dictionaries. The matching is done based on the `if` key. Here's an example:
-
-```yaml
-.base: &base
-  enable:
-    - if: IDF_VERSION == "5.2.0"
-    - if: IDF_VERSION == "5.3.0"
-
-foo:
-  <<: *base
-  enable+:
-    # this if statement dictionary will override the one defined in `&base`
-    - if: IDF_VERSION == "5.2.0"
-      temp: true
-    - if: IDF_VERSION == "5.4.0"
-      reason: bar
-```
-
-After interpretation, the resulting YAML will be:
-
-```yaml
-foo:
-  enable:
-  - if: IDF_VERSION == "5.3.0"
-  - if: IDF_VERSION == "5.2.0"
-    temp: true
-  - if: IDF_VERSION == "5.4.0"
-    reason: bar
-```
-
-In this case, the `enable` list is extended with the new `if` statement and `reason` dictionary.
-It's important to note that the `if` dictionary defined in the `+` postfix will override the earlier one when the `if` statement matches.
-
-This demonstrates how you can use the `+` and `-` postfixes to extend and remove elements from both string and dictionary lists in our YAML.