项目管理

6 个工具处理项目设置、脚手架、芯片选择、设置检查和 IDF 版本 pin。它们合在一起,足以把一个空文件夹变成“准备好构建“,而不需要你打开一次 menuconfig。

工具	做什么
`project.init`	为新项目创建 `.espctl.toml` 和构建文件夹。
`project.create`	从模板创建新 ESP-IDF 项目（hello_world、blink、empty）。
`project.create_component`	向已有项目添加新组件。
`set_target`	修改一个已有项目的芯片 target。
`validate_config`	检查 `.espctl.toml` 文件是不是合法的。
`idf_select_version`(别名 `idf.select_version`)	算出一次构建会用哪个 IDF 版本。

`project.init`

通过创建 .espctl.toml 和标准的构建子目录,在文件夹中设置一个 espctl 项目。

输入:

{
  "target": "esp32s3",
  "idf_version": "v5.3.1",
  "name": "my-project"
}

字段	必需	说明
`target`	是	芯片 —— `esp32`、`esp32s2`、`esp32s3`、`esp32c2`、`esp32c3`、`esp32c6`、`esp32h2`、`esp32p4`。
`idf_version`	否	pin 特定 IDF 版本。默认用构建服务器最新的稳定版。
`name`	否	项目友好名(写进 `.espctl.toml`)。

返回:

{
  "project_root": "/path/to/project",
  "config_path": "/path/to/project/.espctl.toml",
  "target": "esp32s3",
  "idf_version_resolved": "v5.3.1"
}

它对你的项目目录做什么:

如果不存在则创建 .espctl.toml(不会覆盖)。
如果不存在则创建 build/。
写一个默认的 .idf-version 文件 pin IDF 版本(如果你指定了)。

project.init 跑两次没事 —— 第二次什么都不做。

`set_target`

修改一个已经设好的项目的芯片 target。更新 .espctl.toml,重新生成 sdkconfig.defaults,清掉构建缓存。

输入:

{ "target": "esp32c6" }

返回:

{
  "previous_target": "esp32s3",
  "new_target": "esp32c6",
  "rebuild_required": true
}

注意: 切换芯片总是会清掉构建缓存。下一次 build 会是从头开始的完整重建。没有捷径。

CLI: espctl set-target

一个本地小工具:校验芯片名,然后创建 build/<target>/。它不会联系构建服务器,也不会写 .espctl.toml —— 服务器侧的等价工具是 MCP 的 set_target.run。

espctl set-target <target>

输入

参数	说明
`<target>`(位置参数)	`esp32`、`esp32s2`、`esp32s3`、`esp32c2`、`esp32c3`、`esp32c6`、`esp32h2`、`esp32p4` 之一。其它名字会以退出码 2(`invalid target`)失败。

输出

Human 模式:

Target set to esp32s3 (build dir: /path/to/build/esp32s3)

JSON(--json):

{
  "target": "esp32s3",
  "build_dir": "/path/to/build/esp32s3"
}

它实际做了什么

把 <target> 和支持的芯片列表对照校验。
如果 build/<target>/ 不存在就创建(幂等)。
不写 .espctl.toml。下一次 espctl build 会根据这个目录布局决定输出去哪里。

示例

# 把项目切到 ESP32-C3(创建 build/esp32c3/)
espctl set-target esp32c3

# JSON 输出,方便脚本消费
espctl --json set-target esp32s3

`validate_config`

检查一个 .espctl.toml 文件,返回 “valid” 或一个结构化错误。

输入:

{
  "content": "[project]\nname = \"my-app\"\ntarget = \"esp32s3\"\n..."
}

也可以传路径:

{ "path": "/path/to/.espctl.toml" }

返回:

{
  "valid": true,
  "warnings": [],
  "normalized": { ... }
}

…或者失败时:

{
  "valid": false,
  "errors": [
    {
      "line": 7,
      "column": 14,
      "message": "unknown field `targe` (did you mean `target`?)"
    }
  ]
}

这个工具是只读的,可以放心反复调 —— 许多助手在每次编辑 .espctl.toml 之后都会跑一次,做实时校验。

`idf_select_version` / `idf.select_version`

告诉你一次构建会用哪个 IDF 版本,根据项目设置、构建服务器有什么、以及任何明确的 pin。

输入:

{ "version": "v5.3.1" }

version 是可选的。省略时,工具按项目偏好顺序算:

显式的 version 参数
项目的 .idf-version 文件
.espctl.toml 中的 [idf] 节
构建服务器的默认值

返回:

{
  "resolved": "v5.3.1",
  "source": "explicit-argument",
  "store_path": "/var/lib/aegis/espctl-store/idf/v5.3.1",
  "alternatives": ["v5.2.2", "v5.4.0"]
}

source 告诉你为什么选了这个版本,在构建挑了一个意外版本时很有用。 alternatives 列出构建服务器有的所有其他 IDF 版本,助手可以建议升级或降级。

另见

store_versions —— 列出构建服务器有的所有 IDF 版本。
doctor —— 健康检查。
快速开始 —— 用 project.init 设一个新项目。

Keyboard shortcuts

ESP-IDF MCP 用户手册