在 IDF 应用程序中使用 clangd

[English]

clangd 是一款便捷的语言服务器,可在集成开发环境 (IDE) 和编辑器中导航与补全 C 和 C++ 代码。本文介绍如何在编辑器中使用 clangd 进行交叉编译与嵌入式开发。ESP-Clangd 是对 clangd 做了少量补丁的版本,该补丁增加了对自定义配置文件的支持,详见下文 ESP-Clangd 自定义配置。

针对嵌入式项目的调优

在 PC 上进行本地开发时,通常无需任何额外配置。然而,对于嵌入式与交叉编译项目,clangd 往往无法即装即用。通常需要根据项目、编译器和目标进行特殊配置。

下面这些设置对 IDF 应用程序代码以及一般的嵌入式项目都很重要。“重要”提示框中包含对 IDF 代码的推荐设置。

编译数据库

clangd 通过编译数据库 compile_commands.json 获取处理项目代码所需的信息。它会从其中的 command 条目提取编译器路径、目标三元组以及其他信息。构建系统可以生成 compile_commands.json。clangd 会在默认位置查找该文件。(详见 Project setup。)

否则,需要通过 CompileFlags: CompilationDatabase 设置指定包含该数据库的目录。(详见 CompilationDatabase。None 与 Ancestors 为关键词。)

重要

IDF 应用程序使用 CMake 构建,后者会在 build/ 目录 (<project>/build/compile_commands.json) 中生成编译数据库。这是 clangd 的默认位置,因此无需额外配置。

多个 compile_commands.json 数据库

某个项目或构建系统可能会为不同的子目录使用多个 compile_commands.json,例如用于协处理器代码。此时,请在项目配置文件 .clangd 中添加片段 (Fragment),使用 If: PathMatch 来匹配不同路径,并为每个片段分别设置 CompileFlags: CompilationDatabase。(详见 Loading and combining fragments。)

重要

对于 IDF 应用程序中的 ULP 协处理器 C 代码,新建 <project>/.clangd 文件,并写入如下设置:

---
If:
  PathMatch: main/ulp/.*
CompileFlags:
  CompilationDatabase: build/esp-idf/main/ulp_main

--- 是片段 (Fragment) 语法的一部分。路径均相对于 .clangd 文件所在位置。main/ulp/ 目录包含 ULP 协处理器的 C 代码。build/esp-idf/main/ulp_main 目录包含构建系统为 ULP 代码生成的 compile_commands.json 文件。

允许外部编译器

开发嵌入式项目时,请在启动 clangd 时请传入 --query-driver=... 命令行参数。该白名单参数需与 compile_commands.json 配合使用:它通过 glob 模式匹配 command 条目中出现的外部编译器,并告知 clangd 哪些编译器可以安全执行。clangd 会运行匹配的编译器以探测其系统包含路径与内置头文件。

重要

对于 IDF 应用程序,与大多数交叉编译项目一样,向 clangd 传入一个简单的参数:

--query-driver=**

过滤编译器选项

clangd 会使用每个编译数据库条目中 command 字段的选项来调用其内部编译器前端。构建系统可能会使用 clangd 无法识别的选项。可以通过 CompileFlags: Add[] 与 CompileFlags: Remove[] 来过滤这些选项。

重要

默认情况下,IDF 应用程序使用 IDF_TOOLCHAIN=gcc,因此应忽略部分 GCC 特定选项。为简化处理,可移除所有不影响抽象语法树 (AST) 的代码生成选项:

CompileFlags:
  Remove: [-m*, -f*]

如果 IDF 应用程序使用 IDF_TOOLCHAIN=clang 构建,则无需过滤。

内置头文件

内置头文件(也称资源头文件)由编译器提供,有别于标准库头文件,其中包括 stddef.h 与 stdbool.h。

clangd 自带一套默认的内置头文件,但为了更好地匹配目标芯片,建议改用交叉编译工具链提供的内置头文件。请设置 CompileFlags: BuiltinHeaders: QueryDriver,使 clangd 能依据编译数据库定位这些头文件。(详见 BuiltinHeaders。)同时设置合适的 --query-driver= 参数。

重要

若要在 IDF 应用程序中使用乐鑫工具链提供的内置头文件,请设置:

CompileFlags:
  BuiltinHeaders: QueryDriver

clangd 配置

可以使用命令行参数、环境变量和配置文件配置 clangd。这几种配置方式支持的选项并不完全相同,但有些设置是通用的。

配置文件有多个作用域。(详见 Files。)

项目配置文件

可以在源代码树中放置 .clangd 文件。它适用于同一目录及其子目录中的源文件。clangd 会在已打开文件的所有父目录中搜索 .clangd。

对于需要专属设置的应用程序或库,请使用项目配置。

重要

可以在 tools/clangd-config.yaml 中找到适用于 IDF 及 IDF 应用程序代码的推荐设置。

用户配置文件

clangd 会将全局(用户)设置应用到打开的每个文件。用户配置路径为:

  • ~/.config/clangd/config.yaml (Linux)

  • C:\Users\user\AppData\Local\clangd\config.yaml (Windows)

  • ~/Library/Preferences/clangd/config.yaml (macOS)

可以在用户配置中放置通用设置,并使用片段 (Fragment) 与条件 (Condition) 为匹配的路径指定设置。(详见 If。)

ESP-Clangd 自定义配置

ESP-Clangd 增加了命令行参数 --custom-config-file=<path/to/yaml>。自定义配置不受打开文件所在位置影响,因此可以按项目分组使用独立设置(例如面向特定芯片的项目),而无需将其混入用户配置。

自定义配置的优先级高于用户与项目配置。诸如 CompileFlags: Remove[] 这类集合型参数,仍会在各作用域间进行合并。

重要

对于 IDF 应用程序,从编辑器工作区启动 clangd 时,请传入 tools/clangd-config.yaml 的完整路径:

<path/to/tools>/esp-clangd/bin/clangd --custom-config-file=<path/to/IDF>/tools/clangd-config.yaml ...

VS Code 示例

ESP-IDF 会在常规的 ESP-IDF 安装管理器 (EIM) 或 idf_tools.py 安装过程中,连同其他工具一起自动安装 ESP-Clangd。

下面这段 <project>/.vscode/settings.json 配置示例展示了如何配置 VS Code。请按所用编辑器或 IDE 进行相应调整。

{
    "clangd.path": "${env:HOME}/.espressif/tools/esp-clangd/esp-22.1.4_20260825/esp-clangd/bin/clangd",
    "clangd.arguments": [
        "--custom-config-file=${env:HOME}/Path/To/IDF/tools/clangd-config.yaml",
        "--query-driver=**",
        "--log=verbose"
    ]
}

以下为 ESP-IDF 随附的 tools/clangd-config.yaml 文件:

CompileFlags:
  BuiltinHeaders: QueryDriver
  Remove: [-m*, -f*]

此文档对您有帮助吗?