Using Clangd with IDF Applications
Clangd is a handy language server for navigating and completing C and C++ code in IDEs and editors. This guide shows how to use clangd in your editor for cross-compilation and embedded development. ESP-Clangd is a lightly patched version of clangd. The patch adds support for a custom configuration file, described in ESP-Clangd Custom Configuration below.
Tuning for Embedded Projects
For native development on a PC, you usually do not need any extra configuration. However, for embedded and cross-compilation projects, clangd will likely not work out of the box. You often need special configuration, depending on the project, compiler, and target.
The settings below matter for IDF application code, and for embedded projects in general. "Important" blocks contain recommended settings for IDF code.
Compilation Database
Clangd gets what it needs to work with your project code from a compilation database, compile_commands.json. It takes the compiler path, target triple, and other information from the command entry there. Build systems can generate compile_commands.json. Clangd searches for it in the default locations. (See Project setup for details.)
Otherwise, you need to specify the directory containing the database using the CompileFlags: CompilationDatabase setting. (See CompilationDatabase. None and Ancestors are keywords.)
Important
IDF applications are built with CMake, which generates a compilation database in the build/ directory (<project>/build/compile_commands.json). This is the default location for clangd, so no additional configuration is needed.
Multiple compile_commands.json Databases
A project or build system may use multiple compile_commands.json databases for different subdirectories, for example, for coprocessor code. In this case, add Fragments to the Project Configuration .clangd file, using If: PathMatch to match different paths and setting a separate CompileFlags: CompilationDatabase for each fragment. (See Loading and combining fragments.)
Important
For ULP coprocessor C code in an IDF application, add a <project>/.clangd file with the following settings:
---
If:
PathMatch: main/ulp/.*
CompileFlags:
CompilationDatabase: build/esp-idf/main/ulp_main
--- is part of the Fragment syntax. Paths are relative to the location of the .clangd file. The main/ulp/ directory contains C code for the ULP coprocessor. The build/esp-idf/main/ulp_main directory contains the compile_commands.json file generated by the build system for the ULP code.
Allowing External Compiler
When you work with an embedded project, pass the --query-driver=... command-line argument when you start clangd. This allow-list argument works together with compile_commands.json. It specifies glob patterns matching external compilers that appear in the command entries and tells clangd which compilers it can safely execute. Clangd runs a matching compiler to discover its system include paths and built-in headers.
Important
For IDF applications, as for most cross-compilation projects, pass a simple argument to clangd:
--query-driver=**
Filtering Compiler Options
Clangd's internal compiler frontend is invoked with the options in the command field of each compilation database entry. The build system may use options that clangd does not recognize. There are settings CompileFlags: Add[] and CompileFlags: Remove[] to filter such options.
Important
By default, IDF applications are configured to use IDF_TOOLCHAIN=gcc, so some GCC-specific options should be ignored. For simplicity, remove all code generation options that do not affect the AST:
CompileFlags:
Remove: [-m*, -f*]
If the IDF application is built with IDF_TOOLCHAIN=clang, no filtering is needed.
Built-in Headers
Built-in headers (also known as resource headers) are provided by the compiler. These are different from the standard library headers. These include files such as stddef.h and stdbool.h.
Clangd ships with a default set, but for a better match with your target, use the built-in headers from your cross-compilation toolchain instead. Set CompileFlags: BuiltinHeaders: QueryDriver, so that clangd locates them according to the compilation database. (See BuiltinHeaders for details.) Also set the proper --query-driver= argument.
Important
To use the built-in headers from the Espressif toolchain for IDF applications, set the option:
CompileFlags:
BuiltinHeaders: QueryDriver
Clangd Configuration
You can configure clangd with command-line arguments, environment variables, and configuration files. The available options are not identical across these configuration mechanisms, although some settings are shared.
Configuration files are available at several scopes. (See Files for details.)
Project Configuration File
You can place a .clangd file in the source tree. It applies to source files in the same directory and its subdirectories. Clangd searches for .clangd in all parent directories of the open file.
Use the project configuration for an application or a library that needs its own settings.
Important
You can find recommended settings for IDF and IDF application code in tools/clangd-config.yaml.
User Configuration File
Clangd applies the global (user) settings to every file you open. The user configuration is:
~/.config/clangd/config.yaml(Linux)C:\Users\user\AppData\Local\clangd\config.yaml(Windows)~/Library/Preferences/clangd/config.yaml(macOS)
You can put common settings in the user configuration, as well as use Fragments and Conditions to specify settings for matching paths. (See If for details.)
ESP-Clangd Custom Configuration
ESP-Clangd adds the command-line argument --custom-config-file=<path/to/yaml>. The custom configuration applies regardless of where the open file is, so you can use separate settings per group of projects (e.g., projects targeting a specific chip) without mixing it into your user configuration.
The custom configuration takes precedence over the user and project configurations. Set-valued parameters, such as CompileFlags: Remove[], are still merged across all scopes.
Important
For IDF applications, pass the full path to tools/clangd-config.yaml when starting clangd from your editor workspace:
<path/to/tools>/esp-clangd/bin/clangd --custom-config-file=<path/to/IDF>/tools/clangd-config.yaml ...
VS Code Example
ESP-IDF installs ESP-Clangd automatically, together with the other tools, during the usual EIM or idf_tools.py installation.
The following snippet of <project>/.vscode/settings.json shows how you can configure VS Code. Please adapt it to suit your editor or 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"
]
}
This is the tools/clangd-config.yaml file shipped with ESP-IDF:
CompileFlags:
BuiltinHeaders: QueryDriver
Remove: [-m*, -f*]