build-idf

ESP-IDF Build

Applicable Scenarios

Project Profile indicates build_system: idf or the workspace contains an ESP-IDF project structure.
The user wants to perform target chip configuration, compilation, or firmware artifact confirmation for an ESP-IDF project.
The flashing or debugging process requires a new firmware binary file.
It is necessary to confirm whether the ESP-IDF environment is ready before building.

On the first invocation, the following parameters must be confirmed with the user, and must not be skipped or automatically use detected values:

Target chip: even if sdkconfig already contains CONFIG_IDF_TARGET, it must still be confirmed with the user on the first invocation.
IDF_PATH: if the environment variable is already set, show the current value to the user and confirm whether it is correct.

When Project Profile has already recorded the above parameters (i.e., not the first time), they can be reused directly without asking again.

When the script starts, it automatically reuses the last successful profile in the project root directory .em_skill.json as the default parameters (explicit parameters take precedence; there is no need to manually pass --resume）；--resume is only used to assert that the cache must exist, and exits non-zero if there is no cache. When there is no cache or the user explicitly requests re-detection, the script automatically falls back to normal scanning.
Check whether idf.py is available (IDF_PATH is set and the environment is activated).
- ESP-IDF v5.x: activated via source $IDF_PATH/export.sh .
- ESP-IDF v6.0+: activated via EIM (ESP-IDF Installation Manager), such as source ~/.espressif/tools/activate_idf_vX.Y.Z.sh。
Read sdkconfig in CONFIG_IDF_TARGET as a reference (the user still needs to confirm on the first invocation).
Check the CMakeLists.txt and main/ directories to confirm the ESP-IDF project structure.
If there is already a successful build directory and it is consistent with the current intent, reuse it first.
If the target chip is not set and sdkconfig does not exist, you must first execute set-target。

First read references/usage.md, and confirm whether this time is environment detection, target setting, build execution, or artifact scanning only.
If you are unsure whether the environment is ready, first run the built-in script scripts/idf_builder.py 's --detect mode to confirm.
If you need to set or switch the target chip, use --set-target <chip> to execute.
Use --build --project <path> to execute the build.
If the user needs to modify sdkconfig, prompt them to manually run idf.py menuconfig(an interactive command, which must not be executed automatically).
Read the build results and artifact scan report output by the script.
Write the build directory, artifact paths, and target chip information back to Project Profile, and pass it to downstream skills when needed.

When idf.py is unavailable or IDF_PATH is not set, return environment-missing, and prompt the user to manually install ESP-IDF.
When CMakeLists.txt or the main/ directory is missing, return project-config-error。
When there is a compilation error (syntax error, link failure), return project-config-error。
When the build succeeds but no firmware artifact is found, return artifact-missing。
When multiple possible target chips exist and the user has not specified one, return ambiguous-context。

idf.py is a cross-platform Python script and behaves consistently on all host platforms.
The bundled script invokes idf.pyvia subprocess, and you need to ensure the ESP-IDF environment variables are activated.
The build directory defaults to build/。

Output the build command, build directory, target chip, IDF version, and preferred artifact path.
Use artifact_path、artifact_kind、idf_target、idf_version to update Project Profile。
On success, recommend flash-idf。

When the next step is intended to flash the program to hardware, hand off the successful build result to flash-idf。
When the ESP-IDF environment is not installed, prompt the user to install ESP-IDF manually.