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:

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

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

Config Rules
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):

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):

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):

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