build-idf

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ESP-IDF 编译

ESP-IDF Compilation

适用场景

Applicable Scenarios

```
Project Profile
```
中标明
```
build_system: idf
```
或工作区包含 ESP-IDF 工程结构。
用户希望对 ESP-IDF 工程执行目标芯片设置、编译或确认固件产物。
烧录或调试流程需要新的固件二进制文件。
需要在构建前确认 ESP-IDF 环境是否就绪。

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

工作区路径，或一份已有的
```
Project Profile
```
。
目标芯片（esp32、esp32s2、esp32s3、esp32c3、esp32c6、esp32h2 等）。

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

首次参数确认

First-Time Parameter Confirmation

首次调用时，必须向用户确认以下参数，不得跳过或自动使用探测值：

目标芯片：即使
```
sdkconfig
```
中已有
```
CONFIG_IDF_TARGET
```
，首次也必须向用户确认。
IDF_PATH：若环境变量已设置，向用户展示当前值并确认是否正确。

当

Project Profile

中已记录过上述参数（即非首次），可直接复用，无需再次询问。

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

检查
```
idf.py
```
是否可用（
```
IDF_PATH
```
已设置且环境已激活）。
- ESP-IDF v5.x：通过
```
source $IDF_PATH/export.sh
```
  激活。
- ESP-IDF v6.0+：通过 EIM（ESP-IDF Installation Manager）激活，如
```
source ~/.espressif/tools/activate_idf_vX.Y.Z.sh
```
  。
读取
```
sdkconfig
```
中的
```
CONFIG_IDF_TARGET
```
作为参考（首次仍需用户确认）。
检查
```
CMakeLists.txt
```
和
```
main/
```
目录确认 ESP-IDF 工程结构。
若已有成功的构建目录且与当前意图一致，优先复用。
若目标芯片未设置且
```
sdkconfig
```
不存在，必须先执行
```
set-target
```
。

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

先阅读 references/usage.md，确认本次是环境探测、设置目标、执行构建，还是仅扫描产物。
若不确定环境是否就绪，先运行自带脚本 scripts/idf_builder.py 的
```
--detect
```
模式确认。
若需要设置或切换目标芯片，使用
```
--set-target <chip>
```
执行。
使用
```
--build --project <path>
```
执行构建。
若用户需要修改 sdkconfig，提示手动运行
```
idf.py menuconfig
```
（交互式命令，不可自动执行）。
读取脚本输出的构建结果和产物扫描报告。
将构建目录、产物路径、目标芯片信息写回
```
Project Profile
```
，并在需要时交给下游 skill。

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

当
```
idf.py
```
不可用或
```
IDF_PATH
```
未设置时，返回
```
environment-missing
```
，提示用户手动安装 ESP-IDF。
当
```
CMakeLists.txt
```
或
```
main/
```
目录缺失时，返回
```
project-config-error
```
。
当编译错误（语法错误、链接失败）时，返回
```
project-config-error
```
。
当构建成功但未找到固件产物时，返回
```
artifact-missing
```
。
当存在多个可能的目标芯片且用户未指定时，返回
```
ambiguous-context
```
。

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
```
是跨平台的 Python 脚本，在所有宿主平台上行为一致。
自带脚本通过 subprocess 调用
```
idf.py
```
，需要确保 ESP-IDF 环境变量已激活。
构建目录默认为工程根目录下的
```
build/
```
。

```
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

输出构建命令、构建目录、目标芯片、IDF 版本和首选产物路径。

用

artifact_path

、

artifact_kind

、

idf_target

、

idf_version

更新

Project Profile

。

成功后推荐
```
flash-idf
```
。

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

当下一步意图是给硬件烧录程序时，将成功构建结果交给
```
flash-idf
```
。
当 ESP-IDF 环境未安装时，提示用户手动安装 ESP-IDF。

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.