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.

Config File Discovery

idf-build-apps supports a few ways to specify the configuration file (in order of precedence):

specify via CLI argument --config-file <config file path>
.idf_build_apps.toml in the current directory
.idf_build_apps.toml in the parent directories, until it reaches the root of the file system
pyproject.toml with [tool.idf-build-apps] section
pyproject.toml in the parent directories, until it reaches the root of the file system

Usage

We recommend using the .idf_build_apps.toml file for non-Python projects and the pyproject.toml file for Python projects. When using the pyproject.toml file, define the configuration options in the [tool.idf-build-apps] section.

Here’s a simple example of a configuration file:

paths = [
    "components",
    "examples",
]
target = "esp32"
recursive = true

# config rules
config = [
    "sdkconfig.*=",
    "=default",
]

[tool.idf-build-apps]
paths = [
    "components",
    "examples",
]
target = "esp32"
recursive = true

# config rules
config = [
    "sdkconfig.*=",
    "=default",
]

Running idf-build-apps build with the above configuration is equivalent to the following CLI command:

idf-build-app build \
  --paths components examples \
  --target esp32 \
  --recursive \
  --config-rules "sdkconfig.*=" "=default" \
  --build-dir "build_@t_@w"

TOML supports native data types. In order to get the config name and type of the corresponding CLI option, you may refer to the help messages by using idf-build-apps find -h or idf-build-apps build -h.

For instance, the --paths CLI option help message shows:

-p PATHS [PATHS ...], --paths PATHS [PATHS ...]
                     One or more paths to look for apps.
                      - default: None
                      - config name: paths
                      - config type: list[str]

This indicates that in the configuration file, you should specify it with the name paths, and the type should be a “list of strings”.

paths = [
    "foo",
    "bar",
]

CLI Argument Precedence

CLI arguments take precedence over the configuration file. This helps to override the configuration file settings when required.

For example, if the configuration file has the following content:

target = "esp32"
config_rules = [
    "sdkconfig.*=",
    "=default",
]

[tool.idf-build-apps]
target = "esp32"
config_rules = [
    "sdkconfig.*=",
    "=default",
]

Override String Configuration

To override the str type configuration, (e.g., target), you can pass the CLI argument directly:

idf-build-apps build --target esp32s2

Override List Configuration

To override the list[str] type configuration, (e.g., config_rules), you can override it by passing the CLI argument. For example:

idf-build-apps build --config-rules "foo=bar"

Or you can unset the configuration by passing an empty string:

idf-build-apps build --config-rules ""

Override Boolean Configuration

Not supported yet.

Configuration File .idf_build_apps.toml