IDE 集成

espctl ide 用云端构建产物配置本地基于 clangd 的代码补全 —— 不需要本地装 ESP-IDF。它会拉一份 compile_commands.json,把沙箱路径重写到本地 sysroot,再写一份 .vscode/settings.json,让 clangd 扩展开箱就能做跳转和内联诊断。

状态说明: HTTP 下载路径目前是占位实现。espctl ide sync 读你本地 sysroot 里缓存的 compile_commands_raw.json —— 通常是由之前一次成功的同步或本地 agent 构建写下来的。后续版本会直接走 HTTPS 抓。详见下面的限制。

子命令一览

子命令	做什么
`espctl ide sync`	拉 `compile_commands.json`,把路径重写到本地 sysroot,写 `.vscode/settings.json` 给 clangd 用。

espctl ide sync

espctl ide sync [--idf-version <ver>] \
                [--server <url>] \
                [--sysroot <dir>] \
                [--project <dir>] \
                [--job-id <id>]

标志矩阵

标志	默认	说明
`--idf-version`	`.idf-version` → `.espctl.toml` 的 `[idf_version]` → `DEFAULT_IDF_VERSION` 环境变量	通过传递解析后必填。三个来源都没设的话命令会以 `no IDF version found` 退出。
`--server`	`ESPCTL_SERVER` 环境变量 → 已登录的服务器	拉 `compile_commands_raw.json` 的来源(HTTP 通道是占位 —— 见下面的“限制”)。
`--sysroot`	`ESPCTL_SYSROOT` 环境变量 → `~/.espctl/sysroot`	本地 sysroot 的根目录(不是某个版本目录)。
`--project`	当前目录	项目根 —— `compile_commands.json` 和 `.vscode/settings.json` 写到这里。
`--job-id`	上一次构建(预留)	暂未实现;预留给将来固定到某次具体构建。

它写了什么

espctl ide sync 总是会写 <project>/.vscode/settings.json。如果按版本分的 sysroot 目录里有缓存的 compile_commands_raw.json,还会做路径重写后写 <project>/compile_commands.json。

`<project>/.vscode/settings.json`

文件按合并语义写出 —— 你已有的键不会丢,只有 espctl 管的那几个键会被新增或更新:

{
  "clangd.path": "clangd",
  "clangd.arguments": [
    "--background-index",
    "--clang-tidy",
    "--query-driver=<sysroot>/tools/bin/xtensa-esp*-elf-*",
    "--header-insertion=iwyu"
  ],
  "C_Cpp.intelliSenseEngine": "disabled",
  "[c]":   { "editor.defaultFormatter": "llvm-vs-code-extensions.vscode-clangd" },
  "[cpp]": { "editor.defaultFormatter": "llvm-vs-code-extensions.vscode-clangd" },
  "espctl.ideSyncSysroot":    "<sysroot>/<idf-version>",
  "espctl.ideSyncIdfVersion": "<idf-version>"
}

espctl.ideSync* 那两个键是来源标记 —— 告诉将来的运行(和你自己) 这个 .vscode/ 是基于哪个版本生成的。

`<project>/compile_commands.json`

上游 compile_commands_raw.json 里的沙箱路径(例如 /workspace/main/main.c)会被重写到本地 sysroot 路径 (<sysroot>/<idf-version>/main/main.c),clangd 才能找到头文件和工具链。重写由 espctl_core::compile_commands::CompileCommandsRewriter::for_idf_sysroot 完成。

IDE 配置流程

在 VS Code 里安装 clangd 扩展。
用 espctl build 跑一次成功构建,把 compile_commands_raw.json 缓存到本地。
跑 espctl ide sync(可以加 --idf-version vX.Y.Z 固定版本)。
在 VS Code 里重开工作区。clangd 会读到新的 compile_commands.json 并开始建立索引。

限制

HTTP 下载是占位实现。 现在 ide sync 读的是本地 agent 构建 (或之前一次成功 sync)写下的缓存 compile_commands_raw.json。如果两个来源都没有,命令会发警告 No compile_commands.json found; run a build first.,但仍然会把 .vscode/settings.json 写出来。
--job-id 是预留字段,目前没用 —— 命令始终读缓存文件。

示例

# 默认 —— 用 .idf-version、当前目录、~/.espctl/sysroot
espctl ide sync

# 显式指定 IDF 版本
espctl ide sync --idf-version v5.3.1

# 自定义 sysroot 根目录
espctl ide sync --sysroot /opt/espctl-sysroot

# 给另一个路径下的项目配置
espctl ide sync --project /home/me/my-app --idf-version v5.3.1

# 临时覆盖服务器(不持久化登录)
espctl ide sync --server https://staging.esphome.cloud

变量	作用
`ESPCTL_SYSROOT`	覆盖 sysroot 根目录。
`ESPCTL_SERVER`	覆盖服务器 URL。
`DEFAULT_IDF_VERSION`	最后兜底的 IDF 版本。

另见

project://compile_commands —— 暴露同一份编译数据库的底层 MCP 资源。
构建生命周期 —— espctl ide sync 只在至少一次成功构建产出了 compile_commands_raw.json 之后才有意义。
环境变量索引 —— IDE sync 用的 CLI 侧环境变量。

ESP-IDF MCP 用户手册