##########################
 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

.. warning::

   Standalone target-specific sdkconfig files are ignored. To make the target-specific sdkconfig files effective, the original sdkconfig file, (without the target name suffix) must be present.

   For example, ``sdkconfig.ci.foo.esp32`` will only be taken into account while building with target ``esp32`` if ``sdkconfig.ci.foo`` is also present.

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