idf-build-apps 2.4.2__tar.gz → 2.5.0rc0__tar.gz

{idf_build_apps-2.4.2 → idf_build_apps-2.5.0rc0}/.github/workflows/check-pre-commit.yml

@@ -12,7 +12,7 @@ jobs:
           fetch-depth: 0
       - uses: actions/setup-python@v5
       - id: changed-files
-        uses: tj-actions/changed-files@v44
+        uses: tj-actions/changed-files@v45
       - uses: pre-commit/action@v3.0.1
         with:
           extra_args: --files ${{ steps.changed-files.outputs.all_changed_files }}

{idf_build_apps-2.4.2 → idf_build_apps-2.5.0rc0}/.github/workflows/test-build-docs.yml

@@ -19,6 +19,7 @@ jobs:
           flit install -s
       - name: Build the docs
         run: |
-          cd docs && make html
+          cd docs
+          pushd en && make html && popd
       - name: markdown-link-check
         uses: gaurav-nelson/github-action-markdown-link-check@1.0.15

{idf_build_apps-2.4.2 → idf_build_apps-2.5.0rc0}/.github/workflows/test-build-idf-apps.yml

@@ -34,11 +34,11 @@ jobs:
           path: dist/idf_build_apps-*.whl
 
   build-apps-on-idf-env:
-    if: ${{ github.ref == 'refs/heads/main' }}
+    if: ${{ github.ref == 'refs/heads/main' || contains(github.event.pull_request.labels.*.name, 'test-old-idf-releases') }}
     needs: build-python-packages
     strategy:
       matrix:
-        idf-branch: [ release-v5.0, release-v5.1, release-v5.2 ]
+        idf-branch: [ release-v5.0, release-v5.1, release-v5.2, release-v5.3 ]
     runs-on: ubuntu-latest
     container:
       image: espressif/idf:${{ matrix.idf-branch }}
@@ -52,9 +52,12 @@ jobs:
           bash $IDF_PATH/install.sh
           . $IDF_PATH/export.sh
           pip install idf_build_apps-*.whl
-          python -m idf_build_apps build -vv -t esp32 \
-            -p $IDF_PATH/examples/get-started/hello_world \
-            --size-file size_info.json
+          cd $IDF_PATH/examples/get-started/hello_world
+          echo 'CONFIG_IDF_TARGET="esp32"' >sdkconfig.defaults
+          idf-build-apps build --build-dir build_@t --size-file size_info.json
+          test -f build_esp32/hello_world.bin
+          test -f build_esp32/size_info.json
+          test ! -f build_esp32s2/hello_world.bin
 
   build-apps-on-idf-master:
     runs-on: ubuntu-latest

{idf_build_apps-2.4.2 → idf_build_apps-2.5.0rc0}/.gitignore

@@ -69,8 +69,8 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
-docs/api/
+docs/*/_build/
+docs/en/references/api/
 
 # PyBuilder
 .pybuilder/

{idf_build_apps-2.4.2 → idf_build_apps-2.5.0rc0}/.pre-commit-config.yaml

@@ -16,23 +16,31 @@ repos:
           - license_header.txt        # defaults to: LICENSE.txt
           - --use-current-year
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: 'v0.5.5'
+    rev: 'v0.6.2'
     hooks:
       - id: ruff
         args: ['--fix']
       - id: ruff-format
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: 'v1.8.0'   # 1.9 doesn't support python 3.7
+    rev: 'v1.11.2'
     hooks:
       - id: mypy
         args: ['--warn-unused-ignores']
         additional_dependencies:
-          - pydantic<2.6  # 2.6 does not support python 3.7
+          - pydantic
           - packaging
           - toml
           - pyparsing
           - types-PyYAML
           - types-toml
-          - pytest<8  # 8.0.0 does not support python 3.7
+          - pytest
           - argcomplete>=3
-          - annotated_types<0.7.0 # 0.7.0 does not support python 3.7
+  - repo: https://github.com/hfudev/rstfmt
+    rev: v0.1.4
+    hooks:
+      - id: rstfmt
+        args: ['-w', '-1']
+        files: "docs\/.+rst$"
+        additional_dependencies:
+          - sphinx-argparse
+          - sphinxcontrib-mermaid

{idf_build_apps-2.4.2 → idf_build_apps-2.5.0rc0}/.readthedocs.yml

@@ -9,9 +9,6 @@ build:
   tools:
     python: "3.7"
 
-sphinx:
-   configuration: docs/conf.py
-
 python:
   install:
     - method: pip

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

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented in this file.
 
+## v2.5.0rc0 (2024-09-10)
+
+### Feat
+
+- support `idf-build-apps find` with checking modified manfiest files
+- support `idf-build-apps dump-manifest-sha`
+
+### Fix
+
+- loose env var requirements. IDF_PATH not required
+- stop print build log as error when build with warning-as-error
+- requires typing-extensions below 3.11
+- temp build log got wrongly created/deleted
+
+### Refactor
+
+- declare argument once. used in both function, cli, and docs
+- move Manifest.ROOTPATH to params
+
+## v2.4.3 (2024-08-07)
+
+### Feat
+
+- set default building target to "all" if `--target` is not specified
+- set default paths to current directory if `--paths` is not specified
+
 ## v2.4.2 (2024-08-01)
 
 ### Feat
@@ -127,7 +153,7 @@ All notable changes to this project will be documented in this file.
 
 ### BREAKING CHANGES
 
-2.x introduces a lot of breaking changes. For a detailed migration guide, please refer to our [Migration From 1.x to 2.x Guide](https://github.com/espressif/idf-build-apps/blob/main/docs/migration/1.x_to_2.x.md)
+2.x introduces a lot of breaking changes. For a detailed migration guide, please refer to our [Migration From 1.x to 2.x Guide](https://docs.espressif.com/projects/idf-build-apps/en/latest/guides/1.x_to_2.x.html)
 
 Here are the breaking changes:
 

{idf_build_apps-2.4.2 → idf_build_apps-2.5.0rc0}/CONTRIBUTING.md

@@ -15,7 +15,8 @@ Here's a table shows the supported ESP-IDF versions and the corresponding Python
 | 5.0             | 3.7+                              | main (2.x)              |
 | 5.1             | 3.7+                              | main (2.x)              |
 | 5.2             | 3.7+                              | main (2.x)              |
-| master (5.3)    | 3.8+                              | main (2.x)              |
+| 5.3             | 3.8+                              | main (2.x)              |
+| master (5.4)    | 3.8+                              | main (2.x)              |
 
 `idf-build-apps` is following the semantic versioning. The major version of `idf-build-apps` is the same as the ESP-IDF version it supports. For example, `idf-build-apps` 1.x supports ESP-IDF 4.x, and `idf-build-apps` 2.x supports ESP-IDF 5.x.
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: idf-build-apps
-Version: 2.4.2
+Version: 2.5.0rc0
 Summary: Tools for building ESP-IDF related apps.
 Author-email: Fu Hanxi <fuhanxi@espressif.com>
 Requires-Python: >=3.7
@@ -19,7 +19,7 @@ Requires-Dist: packaging
 Requires-Dist: toml; python_version < '3.11'
 Requires-Dist: pydantic~=2.0
 Requires-Dist: argcomplete>=3
-Requires-Dist: typing-extensions ; extra == "dev" and ( python_version < '3.8')
+Requires-Dist: typing-extensions; python_version < '3.11'
 Requires-Dist: sphinx ; extra == "doc"
 Requires-Dist: sphinx-rtd-theme ; extra == "doc"
 Requires-Dist: sphinx_copybutton ; extra == "doc"
@@ -32,7 +32,6 @@ Project-URL: changelog, https://github.com/espressif/idf-build-apps/blob/master/
 Project-URL: documentation, https://docs.espressif.com/projects/idf-build-apps
 Project-URL: homepage, https://github.com/espressif/idf-build-apps
 Project-URL: repository, https://github.com/espressif/idf-build-apps
-Provides-Extra: dev
 Provides-Extra: doc
 Provides-Extra: test
 
@@ -113,5 +112,5 @@ Thanks for your contribution! Please refer to our [Contributing Guide](CONTRIBUT
 [hello-world]: https://github.com/espressif/esp-idf/tree/master/examples/get-started/hello_world
 [supported-targets]: https://github.com/espressif/esp-idf/tree/v5.0#esp-idf-release-and-soc-compatibility
 [doc]: https://docs.espressif.com/projects/idf-build-apps/en/latest/
-[api-doc]: https://docs.espressif.com/projects/idf-build-apps/en/latest/api/modules.html
+[api-doc]: https://docs.espressif.com/projects/idf-build-apps/en/latest/references/api/modules.html
 

{idf_build_apps-2.4.2 → idf_build_apps-2.5.0rc0}/README.md

@@ -75,4 +75,4 @@ Thanks for your contribution! Please refer to our [Contributing Guide](CONTRIBUT
 [hello-world]: https://github.com/espressif/esp-idf/tree/master/examples/get-started/hello_world
 [supported-targets]: https://github.com/espressif/esp-idf/tree/v5.0#esp-idf-release-and-soc-compatibility
 [doc]: https://docs.espressif.com/projects/idf-build-apps/en/latest/
-[api-doc]: https://docs.espressif.com/projects/idf-build-apps/en/latest/api/modules.html
+[api-doc]: https://docs.espressif.com/projects/idf-build-apps/en/latest/references/api/modules.html

{idf_build_apps-2.4.2 → idf_build_apps-2.5.0rc0}/docs/_static/theme_overrides.css

@@ -49,3 +49,7 @@
       font-weight: bold;
       font-style: italic;
   }
+
+pre {
+    white-space: pre-wrap !important;
+}

idf_build_apps-2.5.0rc0/docs/conf_common.py

@@ -0,0 +1,91 @@
+# SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: Apache-2.0
+
+import os
+import shutil
+import subprocess
+
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+from datetime import datetime
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'idf-build-apps'
+project_homepage = 'https://github.com/espressif/idf-build-apps'
+copyright = f'2023-{datetime.now().year}, Espressif Systems (Shanghai) Co., Ltd.'  # noqa: A001
+author = 'Fu Hanxi'
+languages = ['en']
+version = '2.x'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx_copybutton',
+    'myst_parser',
+    'sphinxcontrib.mermaid',
+    'sphinxarg.ext',
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_css_files = ['theme_overrides.css']
+html_logo = '../_static/espressif-logo.svg'
+html_static_path = ['../_static']
+html_theme = 'sphinx_rtd_theme'
+
+# mermaid 10.2.0 will show syntax error
+# use fixed version instead
+mermaid_version = '10.6.1'
+
+autodoc_default_options = {
+    'members': True,
+    'member-order': 'bysource',
+    'show-inheritance': True,
+    'exclude-members': 'model_computed_fields,model_config,model_fields',
+}
+
+
+def generate_api_docs(language):
+    from idf_build_apps.args import (
+        BuildArguments,
+        FindArguments,
+        add_arguments_to_obj_doc_as_params,
+    )
+    from idf_build_apps.main import build_apps, find_apps
+
+    docs_dir = os.path.dirname(__file__)
+    api_dir = os.path.join(docs_dir, language, 'references', 'api')
+    if os.path.isdir(api_dir):
+        shutil.rmtree(api_dir)
+
+    # --- MOCK DOCSTRINGS By Arguments ---
+    add_arguments_to_obj_doc_as_params(FindArguments)
+    add_arguments_to_obj_doc_as_params(BuildArguments)
+    add_arguments_to_obj_doc_as_params(FindArguments, find_apps)
+    add_arguments_to_obj_doc_as_params(BuildArguments, build_apps)
+    # --- MOCK DOCSTRINGS FINISHED ---
+
+    subprocess.run(
+        [
+            'sphinx-apidoc',
+            os.path.join(docs_dir, '..', 'idf_build_apps'),
+            '-f',
+            '-H',
+            'API Reference',
+            '--no-headings',
+            '-t',
+            '_apidoc_templates',
+            '-o',
+            api_dir,
+        ]
+    )

idf_build_apps-2.5.0rc0/docs/en/conf.py

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: Apache-2.0
+
+import os
+import sys
+
+language = 'en'
+
+sys.path.insert(0, os.path.abspath('../'))
+
+from conf_common import *  # noqa
+
+generate_api_docs(language)  # noqa

idf_build_apps-2.5.0rc0/docs/en/explanations/build.rst

@@ -0,0 +1,90 @@
+###############
+ Build Command
+###############
+
+.. note::
+
+   If you are unfamiliar with the the find command yet, please read the :doc:`find` first.
+
+This page explains the process of build apps, and how to use the ``idf-build-apps build`` command to build apps in the projects.
+
+.. note::
+
+   For detailed list of arguments, please refer to the :class:`~idf_build_apps.args.FindArguments` reference.
+
+*************************
+ Basic ``build`` Command
+*************************
+
+.. code:: shell
+
+   idf-build-apps build
+
+*****************************
+ ``build`` With Placeholders
+*****************************
+
+Besides of the :ref:`placeholders supported in find command <find-placeholders>`, the build command also supports the following placeholders:
+
+-  ``@i``: Would be replaced by the build index.
+-  ``@p``: Would be replaced by the parallel build index.
+
+*******************************
+ ``build`` With Warnings Check
+*******************************
+
+You may use `--check-warnings` to enable this check. If any warning is captured while the building process, the exit code would turn to a non-zero value. Besides, `idf-build-apps` provides CLI options `--ignore-warnings-str` and `--ignore-warnings-file` to let you bypass some false alarms.
+
+***************************
+ ``build`` With Debug Mode
+***************************
+
+It's useful to call `--dry-run` with verbose mode `-vv` to know the whole build process in detail before the build actually happens. For example:
+
+.. code:: shell
+
+   idf-build-apps build -p . --recursive --target esp32 --dry-run -vv --config "sdkconfig.ci.*="
+
+The output would be:
+
+.. code:: text
+
+   2024-08-12 15:48:01    DEBUG Looking for CMakeApp apps in . recursively with target esp32
+   2024-08-12 15:48:01    DEBUG Entering .
+   2024-08-12 15:48:01    DEBUG Skipping. . is not an app
+   2024-08-12 15:48:01    DEBUG Entering ./test-1
+   2024-08-12 15:48:01    DEBUG sdkconfig file sdkconfig.defaults not found, checking under app_dir...
+   2024-08-12 15:48:01    DEBUG Use sdkconfig file ./test-1/sdkconfig.defaults
+   2024-08-12 15:48:01    DEBUG Use sdkconfig file /tmp/test/examples/test-1/sdkconfig.ci.bar
+   2024-08-12 15:48:01    DEBUG Found app: (cmake) App ./test-1, target esp32, sdkconfig /tmp/test/examples/test-1/sdkconfig.ci.bar, build in ./test-1/build
+   2024-08-12 15:48:01    DEBUG
+   2024-08-12 15:48:01    DEBUG sdkconfig file sdkconfig.defaults not found, checking under app_dir...
+   2024-08-12 15:48:01    DEBUG Use sdkconfig file ./test-1/sdkconfig.defaults
+   2024-08-12 15:48:01    DEBUG Use sdkconfig file /tmp/test/examples/test-1/sdkconfig.ci.foo
+   2024-08-12 15:48:01    DEBUG Found app: (cmake) App ./test-1, target esp32, sdkconfig /tmp/test/examples/test-1/sdkconfig.ci.foo, build in ./test-1/build
+   2024-08-12 15:48:01    DEBUG
+   2024-08-12 15:48:01    DEBUG => Stop iteration sub dirs of ./test-1 since it has apps
+   2024-08-12 15:48:01    DEBUG Entering ./test-2
+   2024-08-12 15:48:01    DEBUG sdkconfig file sdkconfig.defaults not found, checking under app_dir...
+   2024-08-12 15:48:01    DEBUG sdkconfig file ./test-2/sdkconfig.defaults not found, skipping...
+   2024-08-12 15:48:01    DEBUG Found app: (cmake) App ./test-2, target esp32, sdkconfig (default), build in ./test-2/build
+   2024-08-12 15:48:01    DEBUG
+   2024-08-12 15:48:01    DEBUG => Stop iteration sub dirs of ./test-2 since it has apps
+   2024-08-12 15:48:01     INFO Found 3 apps in total
+   2024-08-12 15:48:01     INFO Total 3 apps. running build for app 1-3
+   2024-08-12 15:48:01     INFO (1/3) Building app: (cmake) App ./test-1, target esp32, sdkconfig /tmp/test/examples/test-1/sdkconfig.ci.bar, build in ./test-1/build
+   2024-08-12 15:48:01     INFO [   Dry Run] Writing build log to ./test-1/build/.temp.build.-4727026790408965348.log
+   2024-08-12 15:48:01     INFO skipped (dry run)
+   2024-08-12 15:48:01     INFO
+   2024-08-12 15:48:01     INFO (2/3) Building app: (cmake) App ./test-1, target esp32, sdkconfig /tmp/test/examples/test-1/sdkconfig.ci.foo, build in ./test-1/build
+   2024-08-12 15:48:01     INFO [   Dry Run] Writing build log to ./test-1/build/.temp.build.4508471977171905517.log
+   2024-08-12 15:48:01     INFO skipped (dry run)
+   2024-08-12 15:48:01     INFO
+   2024-08-12 15:48:01     INFO (3/3) Building app: (cmake) App ./test-2, target esp32, sdkconfig (default), build in ./test-2/build
+   2024-08-12 15:48:01     INFO [   Dry Run] Writing build log to ./test-2/build/.temp.build.4188038822526638365.log
+   2024-08-12 15:48:01     INFO skipped (dry run)
+   2024-08-12 15:48:01     INFO
+   Skipped building the following apps:
+     (cmake) App ./test-1, target esp32, sdkconfig /tmp/test/examples/test-1/sdkconfig.ci.bar, build in ./test-1/build, skipped in 0.000635s: dry run
+     (cmake) App ./test-1, target esp32, sdkconfig /tmp/test/examples/test-1/sdkconfig.ci.foo, build in ./test-1/build, skipped in 0.000309s: dry run
+     (cmake) App ./test-2, target esp32, sdkconfig (default), build in ./test-2/build, skipped in 0.000265s: dry run

idf_build_apps-2.5.0rc0/docs/en/explanations/config_rules.rst

@@ -0,0 +1,203 @@
+##########################
+ Sdkconfig & Config Rules
+##########################
+
+This page explains the concept of `Sdkconfig Files`_ and `Config Rules`_. All examples are based on the following demo project, with the folder structure:
+
+.. code:: text
+
+   test-1/
+   ├── CMakeLists.txt
+   ├── main/
+   │   ├── CMakeLists.txt
+   │   └── test-1.c
+   ├── sdkconfig.ci.bar
+   ├── sdkconfig.ci.foo
+   ├── sdkconfig.ci.foo.esp32
+   ├── sdkconfig.defaults
+   └── sdkconfig.defaults.esp32
+
+*****************
+ Sdkconfig Files
+*****************
+
+In general, `sdkconfig files`_ are text files that contains the Kconfig items in the form of ``key=value`` pairs.
+
+Specifically, in ESP-IDF, the ``sdkconfig`` file is the file that contains all the Kconfig items used by the ESP-IDF build system to configure the build process. The ``sdkconfig`` file is generated by the ESP-IDF build system based on the default Kconfig settings, and the `pre-set configurations`_ values.
+
+Pre-set Configurations
+======================
+
+`Pre-set configurations`_ are the Kconfig items that are set in `sdkconfig files`_ before the real build process starts.
+
+By default, ESP-IDF uses the ``sdkconfig.defaults`` file to set the pre-set configurations.
+
+In ESP-IDF, the target-specific sdkconfig files are used to override the pre-set configurations, when building the project for a specific target. Target-specific sdkconfig files are always endswith the target name. For example, when building the project for the ESP32 target, the ESP-IDF build system will consider the `sdkconfig files`_ with the ``.esp32`` suffix. The values in these target-specific sdkconfig files will override the pre-set values in the ``sdkconfig.defaults`` file. The `override order`_ is explained in more detail in a later section.
+
+.. _config-rules:
+
+**************
+ Config Rules
+**************
+
+In most common CI workflows, the project is built with different configurations. Different combinations of configuration options are tested to ensure the project's robustness.
+
+The `idf-build-apps` tool uses the concept of `config rules`_ to define the way how the project is built with different pre-set configurations. Each matched `sdkconfig file <#sdkconfig-files>`_ will be built into a separate application, which can be used for testing individually at a later stage.
+
+Definition
+==========
+
+To define a Config Rule, use the following format: ``[SDKCONFIG_FILEPATTERN]=[CONFIG_NAME]``.
+
+-  ``SDKCONFIG_FILEPATTERN``: This can be a file name to match a `sdkconfig file <#sdkconfig-files>`_ or a pattern with one wildcard (``*``) character to match multiple `sdkconfig files`_.
+-  ``CONFIG_NAME``: The name of the corresponding build configuration. This value can be skipped if the wildcard value is to be used.
+
+The config rules and the corresponding matched `sdkconfig files`_ for the example project are as follows:
+
+.. list-table:: Config Rules
+   :widths: 15 15 55 15
+   :header-rows: 1
+
+   -  -  Config Rule
+      -  Config Name
+      -  Explanation
+      -  Matched sdkconfig file
+
+   -  -  ``=``
+      -  ``default``
+      -  The default value of the config name is ``default``.
+      -
+
+   -  -  ``sdkconfig.ci.foo=test``
+      -  ``test``
+      -
+      -  ``sdkconfig.ci.foo``
+
+   -  -  ``sdkconfig.not_exists=test``
+      -  ``default``
+      -  The config rule doesn't match any sdkconfig file. The default value is used instead.
+      -
+
+   -  -  ``sdkconfig.ci.*=``
+      -  -  ``foo``
+         -  ``bar``
+      -  The wildcard matches two files. Two apps are built based on each sdkconfig file.
+      -  -  ``sdkconfig.ci.foo``
+         -  ``sdkconfig.ci.bar``
+
+****************
+ Override Order
+****************
+
+The override order is explained using graphs to make it easier to understand.
+
+Basic ``sdkconfig.defaults``
+============================
+
+The matched `sdkconfig files`_ override the pre-set configurations in the ``sdkconfig.defaults`` file. The priority order is as follows (the arrow points to the higher priority):
+
+.. mermaid::
+
+   graph TD
+      A[sdkconfig.defaults]
+      B[sdkconfig.ci.foo]
+      C[sdkconfig.ci.bar]
+      D{{app foo}}
+      E{{app bar}}
+
+      subgraph pre-set configurations
+         A
+         B
+         C
+      end
+
+      A --> B -- "populates sdkconfig file, then build" --> D
+      A --> C -- "populates sdkconfig file, then build" --> E
+
+Target-specific Sdkconfig Files
+===============================
+
+When building the project for the ESP32 target, `sdkconfig files`_ with the ``.esp32`` suffix are considered in addition to the following order (the arrow points to the higher priority):
+
+.. mermaid::
+
+   graph TD
+      A[sdkconfig.defaults]
+      B[sdkconfig.defaults.esp32]
+      C[sdkconfig.ci.foo]
+      D[sdkconfig.ci.foo.esp32]
+      E[sdkconfig.ci.bar]
+      F{{app foo}}
+      G{{app bar}}
+
+      subgraph pre-set configurations
+
+         subgraph only apply when building esp32
+            B
+            D
+         end
+
+         A
+         C
+         E
+      end
+
+      A --> B
+      B --> C --> D -- "populates sdkconfig file, then build" --> F
+      B --> E -- "populates sdkconfig file, then build" --> G
+
+Override In CLI
+===============
+
+``idf-build-apps`` also supports overriding the pre-set configurations using CLI options.
+
+-  ``--override-sdkconfig-items``
+
+   A comma-separated list of key-value pairs representing the configuration options.
+
+-  ``--override-sdkconfig-files``
+
+   A comma-separated list of file paths pointing to the `sdkconfig files`_.
+
+To make the example more complex, assume that the following CLI options are used:
+
+-  ``--override-sdkconfig-items=CONFIG1=VALUE1,CONFIG2=VALUE2``
+-  ``--override-sdkconfig-files=temp1,temp2``
+
+Now the priority order of the configuration options is as follows (the arrow points to the higher priority):
+
+.. mermaid::
+
+   graph TD
+      A[sdkconfig.defaults]
+      B[sdkconfig.defaults.esp32]
+      C[sdkconfig.ci.foo]
+      D[sdkconfig.ci.foo.esp32]
+      E[sdkconfig.ci.bar]
+      F[temp1]
+      G[temp2]
+      H[A temp file, that contains the value of --override-sdkconfig-items
+      CONFIG1=VALUE1
+      CONFIG2=VALUE2]
+
+      I{{app foo}}
+      J{{app bar}}
+
+      subgraph pre-set configurations
+
+         subgraph only apply when building esp32
+            B
+            D
+         end
+
+         A
+         C
+         E
+         F
+         G
+         H
+      end
+
+      A --> B
+      B --> C --> D --> F --> G --> H -- "populates sdkconfig file, then build" --> I
+      B --> E --> F --> G --> H -- "populates sdkconfig file, then build" --> J