IDF Build Apps

3.0.1 · active · verified Thu Apr 16

idf-build-apps is a Python library and command-line tool designed to streamline the process of building, flashing, and testing multiple ESP-IDF applications. It integrates deeply with the ESP-IDF CMake-based build system, offering functionalities for finding, building, and flashing projects across various targets. The current version is 3.0.1, with releases typically following ESP-IDF major updates or bug fixes.

Common errors

```
ValueError: 'IDF_PATH' environment variable is not set. Please set the path to ESP-IDF.
```
cause The Python environment or the shell from which idf-build-apps is executed does not have the IDF_PATH environment variable configured.

fix Set the `IDF_PATH` environment variable to the root directory of your ESP-IDF installation. For example, `export IDF_PATH=/path/to/esp-idf` in your shell, or configure it in your build script.
```
RuntimeError: No apps found under path: ...
```
cause The `find_apps` function could not locate any valid ESP-IDF projects (directories containing `CMakeLists.txt` and optionally `sdkconfig`) within the specified `search_paths` and `recursive` settings.

fix Verify that `search_paths` points to the correct directory containing your ESP-IDF apps, and that `recursive=True` is set if your apps are in subdirectories. Ensure `CMakeLists.txt` files are present in the app roots.
```
The target python version must be >= 3.10
```
cause You are attempting to run `idf-build-apps` version 3.0.0 or higher with a Python interpreter older than 3.10.

fix Upgrade your Python installation to version 3.10 or newer, or activate a virtual environment that uses Python 3.10+.
```
CMake Error at CMakeLists.txt:X (include): include could not find load file: /path/to/esp-idf/tools/cmake/project.cmake
```
cause The `IDF_PATH` environment variable is either incorrectly set, points to a non-existent directory, or the ESP-IDF installation is incomplete/corrupted, preventing CMake from finding core project files.

fix Double-check that `IDF_PATH` points to the correct and complete ESP-IDF installation directory. If necessary, re-download or re-install ESP-IDF.

Warnings

breaking idf-build-apps v3.0.0 and newer require Python 3.10 or higher. Previous versions (2.x) supported older Python versions.
Fix: Upgrade your Python environment to 3.10 or newer. If you must use an older Python, stick to idf-build-apps v2.x.
gotcha The `IDF_PATH` environment variable must be correctly set and point to a valid ESP-IDF installation for any build or flash operations to succeed. `idf-build-apps` relies on ESP-IDF's toolchain.
Fix: Ensure `IDF_PATH` is set in your shell environment before running `idf-build-apps` commands or Python scripts. You might need to source ESP-IDF's `export.sh` script.
breaking The `recursive` parameter in `find_apps()` changed its default value from `False` to `True` in v3.0.0. This means `find_apps` will now recursively search for apps by default.
Fix: If you rely on the old non-recursive behavior, explicitly set `recursive=False` when calling `find_apps()`.
breaking Some arguments for `flash_apps` have been renamed or removed in v3.0.0. For example, `erase_all` was replaced by `erase_nvs` to be more explicit about its function.
Fix: Review your `flash_apps` calls and update argument names according to the v3.0.0 documentation. For `erase_all`, use `erase_nvs` for similar functionality or consult docs for other changes.

Install

pip install idf-build-apps Install latest version

Imports

build_apps
```
from idf_build_apps import build_apps
```
find_apps
```
from idf_build_apps import find_apps
```
flash_apps
```
from idf_build_apps import flash_apps
```

Quickstart

This quickstart demonstrates how to use `idf-build-apps` to find and perform a dry run build for multiple ESP-IDF applications. It creates a temporary directory with two dummy ESP-IDF projects to ensure the example is runnable even without a pre-existing project structure. It highlights the crucial `IDF_PATH` environment variable and uses `dry_run=True` for safe execution. For a real build, set `dry_run=False` and ensure `IDF_PATH` points to your ESP-IDF installation.

import os
import shutil
from pathlib import Path
from idf_build_apps import build_apps, find_apps

# --- Create dummy ESP-IDF app structure for demonstration ---
# In a real scenario, 'my_app_1' and 'my_app_2' would be your actual ESP-IDF project directories.
# This setup allows the example to run without a complete ESP-IDF project, using dry_run.

dummy_root = Path('./idf_build_apps_quickstart_temp')
dummy_root.mkdir(exist_ok=True)

app1_path = dummy_root / 'my_app_1'
app1_path.mkdir(exist_ok=True)
(app1_path / 'CMakeLists.txt').write_text('cmake_minimum_required(VERSION 3.16)\ninclude($ENV{IDF_PATH}/tools/cmake/project.cmake)\nproject(my_app_1)')
(app1_path / 'sdkconfig').write_text('CONFIG_FREERTOS_HZ=100\n')
(app1_path / 'main.c').write_text('void app_main() {}')

app2_path = dummy_root / 'my_app_2'
app2_path.mkdir(exist_ok=True)
(app2_path / 'CMakeLists.txt').write_text('cmake_minimum_required(VERSION 3.16)\ninclude($ENV{IDF_PATH}/tools/cmake/project.cmake)\nproject(my_app_2)')
(app2_path / 'sdkconfig').write_text('CONFIG_FREERTOS_HZ=100\n')
(app2_path / 'main.c').write_text('void app_main() {}')

# --- Set up environment for idf-build-apps (critical) ---
# For actual building, IDF_PATH must point to a valid ESP-IDF installation.
# We use a placeholder here for dry_run to avoid immediate failure.
if 'IDF_PATH' not in os.environ:
    print("WARNING: IDF_PATH environment variable is not set. Using a placeholder for dry_run.")
    os.environ['IDF_PATH'] = '/path/to/esp-idf' # Replace with your actual ESP-IDF path

# --- Find applications ---
print(f"Searching for apps in: {dummy_root}")
apps = find_apps(
    dummy_root, # The root directory to search for apps
    recursive=True,
    target='esp32', # Specify the target chip (e.g., esp32, esp32s3)
    build_dir_name='build_idf_apps' # Name for the build output directory
)

print(f"Found {len(apps)} apps:")
for app in apps:
    print(f"  - {app.path.name} (target: {app.target}, build_dir: {app.build_path})")

# --- Build applications (dry run for safety and demonstrability) ---
# Set dry_run=False and ensure IDF_PATH is correct for a real build.
try:
    build_apps(
        apps,
        parallel_jobs=1, # Number of parallel build jobs
        dry_run=True, # Set to False for a real build
        verbose=True,
        # You can also pass 'work_dir', 'keep_partial_results', etc.
    )
    print("\nSuccessfully completed dry run for building apps.")
    print("To perform an actual build, set 'dry_run=False' and ensure 'IDF_PATH' is correctly configured.")
except Exception as e:
    print(f"\nAn error occurred during the build (dry_run): {e}")
    print("This might be expected if IDF_PATH is not fully set up for a real ESP-IDF build.")

# --- Clean up dummy files ---
# shutil.rmtree(dummy_root)
# print(f"Cleaned up temporary directory: {dummy_root}")

view raw JSON →