{"id":8224,"library":"idf-build-apps","title":"IDF Build Apps","description":"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.","status":"active","version":"3.0.1","language":"en","source_language":"en","source_url":"https://github.com/espressif/idf-build-apps","tags":["ESP-IDF","embedded","build-system","automation","esp32"],"install":[{"cmd":"pip install idf-build-apps","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"build_apps","correct":"from idf_build_apps import build_apps"},{"symbol":"find_apps","correct":"from idf_build_apps import find_apps"},{"symbol":"flash_apps","correct":"from idf_build_apps import flash_apps"}],"quickstart":{"code":"import os\nimport shutil\nfrom pathlib import Path\nfrom idf_build_apps import build_apps, find_apps\n\n# --- Create dummy ESP-IDF app structure for demonstration ---\n# In a real scenario, 'my_app_1' and 'my_app_2' would be your actual ESP-IDF project directories.\n# This setup allows the example to run without a complete ESP-IDF project, using dry_run.\n\ndummy_root = Path('./idf_build_apps_quickstart_temp')\ndummy_root.mkdir(exist_ok=True)\n\napp1_path = dummy_root / 'my_app_1'\napp1_path.mkdir(exist_ok=True)\n(app1_path / 'CMakeLists.txt').write_text('cmake_minimum_required(VERSION 3.16)\\ninclude($ENV{IDF_PATH}/tools/cmake/project.cmake)\\nproject(my_app_1)')\n(app1_path / 'sdkconfig').write_text('CONFIG_FREERTOS_HZ=100\\n')\n(app1_path / 'main.c').write_text('void app_main() {}')\n\napp2_path = dummy_root / 'my_app_2'\napp2_path.mkdir(exist_ok=True)\n(app2_path / 'CMakeLists.txt').write_text('cmake_minimum_required(VERSION 3.16)\\ninclude($ENV{IDF_PATH}/tools/cmake/project.cmake)\\nproject(my_app_2)')\n(app2_path / 'sdkconfig').write_text('CONFIG_FREERTOS_HZ=100\\n')\n(app2_path / 'main.c').write_text('void app_main() {}')\n\n# --- Set up environment for idf-build-apps (critical) ---\n# For actual building, IDF_PATH must point to a valid ESP-IDF installation.\n# We use a placeholder here for dry_run to avoid immediate failure.\nif 'IDF_PATH' not in os.environ:\n    print(\"WARNING: IDF_PATH environment variable is not set. Using a placeholder for dry_run.\")\n    os.environ['IDF_PATH'] = '/path/to/esp-idf' # Replace with your actual ESP-IDF path\n\n# --- Find applications ---\nprint(f\"Searching for apps in: {dummy_root}\")\napps = find_apps(\n    dummy_root, # The root directory to search for apps\n    recursive=True,\n    target='esp32', # Specify the target chip (e.g., esp32, esp32s3)\n    build_dir_name='build_idf_apps' # Name for the build output directory\n)\n\nprint(f\"Found {len(apps)} apps:\")\nfor app in apps:\n    print(f\"  - {app.path.name} (target: {app.target}, build_dir: {app.build_path})\")\n\n# --- Build applications (dry run for safety and demonstrability) ---\n# Set dry_run=False and ensure IDF_PATH is correct for a real build.\ntry:\n    build_apps(\n        apps,\n        parallel_jobs=1, # Number of parallel build jobs\n        dry_run=True, # Set to False for a real build\n        verbose=True,\n        # You can also pass 'work_dir', 'keep_partial_results', etc.\n    )\n    print(\"\\nSuccessfully completed dry run for building apps.\")\n    print(\"To perform an actual build, set 'dry_run=False' and ensure 'IDF_PATH' is correctly configured.\")\nexcept Exception as e:\n    print(f\"\\nAn error occurred during the build (dry_run): {e}\")\n    print(\"This might be expected if IDF_PATH is not fully set up for a real ESP-IDF build.\")\n\n# --- Clean up dummy files ---\n# shutil.rmtree(dummy_root)\n# print(f\"Cleaned up temporary directory: {dummy_root}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or newer. If you must use an older Python, stick to idf-build-apps v2.x.","message":"idf-build-apps v3.0.0 and newer require Python 3.10 or higher. Previous versions (2.x) supported older Python versions.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"If you rely on the old non-recursive behavior, explicitly set `recursive=False` when calling `find_apps()`.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The Python environment or the shell from which idf-build-apps is executed does not have the IDF_PATH environment variable configured.","error":"ValueError: 'IDF_PATH' environment variable is not set. Please set the path to ESP-IDF."},{"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.","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.","error":"RuntimeError: No apps found under path: ..."},{"fix":"Upgrade your Python installation to version 3.10 or newer, or activate a virtual environment that uses Python 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.","error":"The target python version must be >= 3.10"},{"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.","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.","error":"CMake Error at CMakeLists.txt:X (include): include could not find load file: /path/to/esp-idf/tools/cmake/project.cmake"}]}