Clangd 与编译数据库

clangd 使用虚拟编译器命令解析每个打开的文件，从而提供 C 和 C++ 语言服务器功能。只有当该命令代表真实构建上下文时，补全、诊断、导航和重构才可靠；上下文包括工作目录、编译器驱动程序、目标、语言模式、包含路径、预处理器定义和生成的头文件。

提供编译命令 #

编译数据库是首选事实来源。compile_commands.json 为每个翻译单元包含一条命令和一个工作目录。CMake 可以为构建树生成它：

cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
clangd --compile-commands-dir=build

[
  {
    "directory": "/work/project",
    "file": "src/main.cc",
    "command": "clang++ -Iinclude -std=c++20 -c src/main.cc"
  }
]

没有 --compile-commands-dir 时，clangd 会从打开文件所在目录向上级目录搜索 compile_commands.json 或 compile_flags.txt。compile_flags.txt 是更简单的备用方案：它为每个文件提供每行一个标志，无法表示不同翻译单元具有不同标志的目标。

-Iinclude
-std=c++20
-Wall

从权威构建生成数据库，然后让工作区能够发现它。从仓库根目录建立符号链接、使用编辑器设置或指定 --compile-commands-dir 都有效；复制数据库可能导致命令过时。对于没有原生支持的构建系统，Bear 等工具可以观察一次干净构建，但生成的命令仍必须描述开发者打开的配置。

头文件、新文件与标志调整 #

构建系统不会直接编译头文件。对于头文件，clangd 首先复用某个已打开且包含该头文件的源文件命令；否则会选择文件名相似的数据库条目。在多平台代码树中，这种启发式方法可能选择错误目标。应先打开包含该头文件的源文件，使头文件命名与其主要源文件保持一致，或使用项目配置明确指定上下文。

数据库中不存在的文件会获得备用命令。备用命令允许解析，但不包含构建提供的目标专用包含路径、宏、生成头文件或语言模式。应将其诊断视为暂时结果，并在编辑新目标前将源文件加入构建或提供配置。

.clangd can adjust commands without duplicating the database:

CompileFlags:
  Add: [-Ithird_party/api, -DMY_EDITOR_BUILD=1]
  Remove: [-Werror]

使用调整来处理仅限编辑器的修正或 clangd 无法使用的标志，不要借此手工重建构建命令。尽可能保留编译器可执行文件，因为其位置和名称会影响默认标准库查找和语言选择。

诊断错误上下文 #

Run a single-file check and inspect the selected command:

clangd --check=src/main.cc --log=verbose

详细日志会标识编译数据库、工作目录和调整后的命令。当找不到头文件时，将 -I、-isystem、sysroot 和生成头文件路径与实际编译调用进行比较。当解析使用错误方言时，检查 -x、-std=、Objective-C 与 C++ 的区别以及编译器驱动程序。当内置类型或 ABI 相关类型不一致时，检查 --target、工具链路径和 SDK 标志。

更改构建选项、依赖或生成源文件后，重新生成数据库。确保代码生成器在 clangd 使用输出之前运行，或提供生成的包含目录和已提交的接口头文件。使用额外的 clangd 标志 启动 LSP 服务器，与更改文件的 编译命令 不同；源代码语义应使用后者。