ESP-IDF Compilation

Applicable Scenarios

The
```
Project Profile
```
specifies
```
build_system: idf
```
or the workspace contains an ESP-IDF project structure.
Users want to perform target chip configuration, compilation, or confirm firmware artifacts for an ESP-IDF project.
A new firmware binary is required for flashing or debugging processes.
Need to confirm whether the ESP-IDF environment is ready before building.

Required Inputs

Workspace path, or an existing
```
Project Profile
```
.
Target chip (esp32, esp32s2, esp32s3, esp32c3, esp32c6, esp32h2, etc.).

First-Time Parameter Confirmation

When calling for the first time, the following parameters must be confirmed with the user, and cannot be skipped or automatically detected values used:

Target Chip: Even if
```
CONFIG_IDF_TARGET
```
exists in
```
sdkconfig
```
, it must be confirmed with the user for the first time.
IDF_PATH: If the environment variable has been set, display the current value to the user and confirm whether it is correct.

When the above parameters have been recorded in the

Project Profile

(i.e., not the first time), they can be directly reused without asking again.

Automatic Detection

Check if
```
idf.py
```
is available (the
```
IDF_PATH
```
is set and the environment is activated).
- ESP-IDF v5.x: Activate via
```
source $IDF_PATH/export.sh
```
  .
- ESP-IDF v6.0+: Activate via EIM (ESP-IDF Installation Manager), such as
```
source ~/.espressif/tools/activate_idf_vX.Y.Z.sh
```
  .
Read
```
CONFIG_IDF_TARGET
```
in
```
sdkconfig
```
as a reference (still need user confirmation for the first time).
Check the
```
CMakeLists.txt
```
and
```
main/
```
directory to confirm the ESP-IDF project structure.
If there is an existing successful build directory that matches the current intent, prioritize reusing it.
If the target chip is not set and
```
sdkconfig
```
does not exist,
```
set-target
```
must be executed first.

Execution Steps

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

Failure Diversion

When
```
idf.py
```
is unavailable or
```
IDF_PATH
```
is not set, return
```
environment-missing
```
and prompt the user to manually install ESP-IDF.
When the
```
CMakeLists.txt
```
or
```
main/
```
directory is missing, return
```
project-config-error
```
.
When compilation errors occur (syntax errors, linking failures), return
```
project-config-error
```
.
When the build is successful but no firmware artifacts are found, return
```
artifact-missing
```
.
When multiple possible target chips exist and the user has not specified, return
```
ambiguous-context
```
.

Platform Notes

```
idf.py
```
is a cross-platform Python script that behaves consistently on all host platforms.
The built-in script calls
```
idf.py
```
via subprocess, which requires ensuring that the ESP-IDF environment variables are activated.
The build directory defaults to
```
build/
```
under the project root directory.

Output Conventions

Output the build command, build directory, target chip, IDF version, and preferred artifact path.

Update the

Project Profile

with

artifact_path

artifact_kind

idf_target

idf_version

Recommend
```
flash-idf
```
after success.

Handover Relationships

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

build-idf

NPX Install

Tags

SKILL.md Content (Chinese)