C-Journey

主题

正常

VSCode + Clangd:把工具链接进编辑器 ​

引言:命令行通了,然后呢 ​

第 1 章我们把 gcc、clang、gdb、make、cmake 一件件在命令行里跑通了,还立了一条纪律:「命令行能跑通才算真的通」。这一章不推翻它,而是把它坐实。

你在第 1 章末尾大概有过这个念头:命令行是清楚,可总不能光靠 grep 和 printf 读代码吧——写个大点的工程,想点一下函数名就跳到定义、想敲半个名字就补全、想写错类型就当场画红线,这些「编辑器该有的本事」难道和命令行工具链是两套世界?

很多人就是在这一步滑回 IDE 的怀抱——装个 Visual Studio、点一下绿色运行按钮、屏幕蹦出 hello world,挺美。但第 1 章说清了这份省心的代价:IDE 替你把编译器、调试器全打包了,你不知道它们叫什么、装在哪,换台机器、丢进 CI 就抓瞎。我们换一条路:把命令行那套工具链,原样接进一个轻壳编辑器。

这一章就干这件事,工具是 VSCode + 一个叫 clangd 的语言服务器。clangd 的哲学正好和第 1 章那条纪律同向——它不另起炉灶,而是读你命令行那套 flags(-std、-I、-Wall 这些),据此给你跳转、补全、诊断。换句话说,IDE 不是另一个世界,是你刚体检过的工具链的一个视图。视图画歪了,根子还是在命令行那套 flags 上——这就是本章要帮你打通的关节。

三件套各自的职责 ​

先把三个名字分清,别混。

VSCode 是个轻壳编辑器——它自己不会编译 C、也不懂 C 语法,只负责显示文本、管文件、跑扩展。第 1 章说过它是「壳」、不替你包办,这一章你正好把这句话兑现。

clangd 是个语言服务器(LSP,Language Server Protocol)。它是个独立进程:你装它的 VSCode 扩展、扩展启动后台的 clangd 进程,VSCode 把你光标位置、你敲的字符转告给它,它把「这个函数定义在哪」「这个名字怎么补全」「这行有什么错」算出来回传给 VSCode 显示。clangd 背后就是 clang——和你第 1 章命令行里敲的 clang 是同一个前端,只是不开代码生成、只做语法语义分析。所以 clangd 给你的诊断,和命令行 clang 编译时的警告/错误,是同一套。

CMake 这章我们还不深入(留到第 13 章),但你先知道一件事:它能替你产出 clangd 要吃的那份 flags 清单。这一章我们先用手写的最小清单,第 13 章再升级。

本机版本(和你第 1 章体检到的工具链同源):

text
$ clangd --version
clangd version 22.1.8
Features: linux
Platform: x86_64-pc-linux-gnu

最小验证:compile_flags.txt 让 clangd 认识你的代码 ​

clangd 要干活,第一个问题就是:它怎么知道你的 greet.c 是用什么 flags 编的?没有 -std,它不知道按 C11 还是 C23 解析(第 1 章真跑过 gcc 16 默认 C23、clang 22 默认 C17,差一截);没有 -I,它不知道去哪找自定义头文件,跳转直接瞎。所以你得给它一份「编译这个文件用的 flags」。

最省事的方式是 compile_flags.txt:一个纯文本,每行一个 flag,放在源码目录里。我们拿一个极简的两文件工程当小白鼠(承第 12 章 make、第 13 章 cmake 都用过的那个 greet,熟面孔):

c
/* include/greet.h */
#ifndef GREET_H
#define GREET_H
void greet(const char *name);
#endif
c
/* greet.c */
#include <stdio.h>
#include "greet.h"

void greet(const char *name) {
    printf("Hello, %s!\n", name);
}

int main(void) {
    greet("C-Journey");
    return 0;
}

头文件我故意放进 include/ 子目录、而不是和 greet.c 同级——这样它就不在「源文件当前目录」里,必须靠 -I 显式指出来才找得到,后面演示坑的时候你才看得出区别。命令行编译要先通(第 1 章那条纪律):

text
$ gcc -std=c11 -Wall -Wextra -Iinclude greet.c -o greet && ./greet
Hello, C-Journey!
$ clang -std=c11 -Wall -Wextra -Iinclude greet.c -o greet && ./greet
Hello, C-Journey!

好,命令行通了。现在把这套 flags 原样写进 compile_flags.txt,每行一个:

text
-std=c11
-Wall
-Wextra
-Iinclude

clangd 怎么确认它真读到了这份 flags、真把 greet.c 解析对了?它有个 --check 模式,不开 LSP、就在终端里把整个解析过程打一遍——这正是「命令行真跑贴输出」的好工具,不靠 GUI 截图:

text
$ clangd --check=greet.c
I[...] clangd version 22.1.8
I[...] Working directory: /tmp/cj/ch2
I[...] Testing on source file /tmp/cj/ch2/greet.c
I[...] Loading compilation database...
I[...] Loaded compilation database from /tmp/cj/ch2/compile_flags.txt
I[...] Compile command from CDB is: [/tmp/cj/ch2] /usr/bin/clang-tool -std=c11 -Wall -Wextra -Iinclude -resource-dir=/usr/lib/clang/22 -- /tmp/cj/ch2/greet.c
...
I[...] All checks completed, 0 errors

读法挑三行:Loaded compilation database from .../compile_flags.txt 说明它找到了你的 flags 清单;Compile command ... -std=c11 -Wall -Wextra -Iinclude ... 说明它逐字用上了你写的那四个 flag——和你命令行敲的 gcc -std=c11 -Wall -Wextra -Iinclude 是一回事;最后 All checks completed, 0 errors 说明 greet.c 在这套 flags 下解析干净。到这一步,clangd 已经认识你的代码了。

真正的坑:漏一个 -I,跳转就静默瞎掉 ​

flags 这么重要,那漏一个会怎样?这是本章最该带走的一个直觉——clangd 的 flags 一旦和命令行对不上,它不会报错崩给你看,而是静默地变瞎。你点 greet( 想跳到定义,跳不过去;你打 gre 想补全,补不出来;诊断面板也不提示「你的 compile_flags 少了 -I」。它就是默默地、什么都不给你。

我把 compile_flags.txt 里的 -Iinclude 删掉,再跑一次 clangd --check,你看对比:

text
$ clangd --check=greet.c   # compile_flags.txt 里没了 -Iinclude
...
E[...] [pp_file_not_found] Line 2: 'greet.h' file not found
E[...] IncludeCleaner: Failed to get an entry for resolved path '' from include "greet.h" : No such file or directory

'greet.h' file not found——clangd 找不到 greet.h 了,因为它不知道要去 include/ 目录下找(你没告诉它)。在 VSCode 里这条对应的不是一句醒目的红字,而是「点 greet( 跳不动」这种沉默的失效——你大概率会以为是扩展坏了、或者 VSCode 卡了,绕一大圈才意识到根因在 compile_flags.txt 少了一行。

这就是为什么第 1 章反复强调「命令行那套 flags 才是真相」:clangd 不是另搞一套,它只是复刻命令行的 flags;你命令行能编通、flags 写进 compile_flags.txt 一字不差,clangd 就稳;漏一个,它就瞎。工具链的真相没变,变的只是它被接进了编辑器。

VSCode 侧:装 clangd 扩展,看它工作 ​

compile_flags.txt 在后台对上了,现在把 VSCode 这头接上。

先装扩展。VSCode 的 C/C++ 生态里有两个容易混的扩展,你得挑对:clangd(llvm 官方,扩展 ID 是 llvm.clangd)和我们不首选的微软 C/C++ 扩展(ms-vscode.cpptools)。区别在于:微软那个自带一套 IntelliSense 语言服务器(和 clangd 同类、会冲突),它的强项在调试器(cppdbg);clangd 的语言服务比微软 IntelliSense 快且准(尤其对模板、对跨文件跳转),所以社区里 C 工程的主流搭配是「clangd 管语言、微软 C/C++ 只借用它的调试器、把它自己的 IntelliSense 关掉」。装 clangd 扩展时它会检测到微软那个、自动帮你禁用 IntelliSense,不用手动折腾。

装好后,VSCode 打开 /tmp/cj/ch2/ 这个目录(File → Open Folder,而不是单开一个文件——compile_flags.txt 是按目录生效的)。clangd 扩展会启动后台 clangd 进程,读你的 compile_flags.txt,开始解析。

怎么确认它真在工作?看它的日志。Ctrl+Shift+P → 输 clangd → 选 Output 面板的 clangd 频道,你会看到和上面 --check 同样的日志流:Loaded compilation database from .../compile_flags.txt。这条出现,就说明 VSCode 里的 clangd 和你命令行的 clangd --check 吃的是同一份 flags——视图和真相接上了。

接上之后,试这几件事。光标停在 greet( 调用上按 F12(或右键 Go to Definition),跳到 include/greet.h 里那行声明。打 gre 自动补出 greet。把 greet.c 里 printf("Hello, %s!\n", name); 故意删一个右括号变成 printf("Hello, %s!\n", name;,编辑器下方 Problems 面板立刻给你红线、报「expected )」——和命令行 gcc 编译时报的错是同一句。这就是第 1 章那条「IDE 不替你包办、但工具链能力能接进来」落地后的样子。

接上构建:最小的 tasks.json ​

编辑能跳转了,但每次编译还要切回终端敲 gcc ... 也烦。VSCode 的 tasks.json 就是把那行命令包成快捷键:它本身不编译,只是替你跑一条 shell。

在工程根目录建 .vscode/tasks.json,内容是一个 build 任务:

json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build",
      "type": "shell",
      "command": "gcc",
      "args": ["-std=c11", "-Wall", "-Wextra", "-Iinclude", "greet.c", "-o", "greet"],
      "group": { "kind": "build", "isDefault": true },
      "problemMatcher": ["$gcc"]
    }
  ]
}

command 和 args 拼起来,就是你在终端敲的那行 gcc -std=c11 -Wall -Wextra -Iinclude greet.c -o greet——一字不差。group 里 isDefault: true 让它成为默认构建任务,Ctrl+Shift+B 直接触发;problemMatcher: ["$gcc"] 这条很值钱,它把 gcc 的报错格式解析成「文件:行:列」,你 Ctrl+Shift+B 编完、有报错的话点 Problems 面板就能跳到出错行——和 clangd 的实时诊断互补(一个抓编译时的错、一个抓你敲字时的错)。这条 task 等价于命令行,所以第 1 章验证过的命令行能跑通、它就能跑通。

接上调试:最小的 launch.json(点到为止) ​

最后一步是调试,但调试技巧不在这展开——这一章只负责把 VSCode 的 F5 和 gdb 接上,怎么下断点、怎么看栈、怎么读 core dump,统统归第 14、15 章(那两章在命令行 gdb 上扎得更深)。

接法是 .vscode/launch.json,一个最小配置:

json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "gdb 启动 greet",
      "type": "cppdbg",
      "request": "launch",
      "program": "${workspaceFolder}/greet",
      "args": [],
      "cwd": "${workspaceFolder}",
      "MIMode": "gdb",
      "miDebuggerPath": "gdb"
    }
  ]
}

type: cppdbg 用的是微软 C/C++ 扩展的调试器(就是前面说「借用它的调试器」那一句的落点);MIMode: gdb 和 miDebuggerPath: gdb 告诉它底层调试器是第 1 章体检过的那个 gdb 17.2——不是 VSCode 自己发明的另一套,就是你命令行 gdb ./greet 那个 gdb,只是把命令包成了图形界面。按 F5、greet 在调试器里跑起来,你能下断点、看变量。再强调一句:调试技巧(条件断点、watchpoint、core dump)不在这重复,它们和命令行 gdb 是同一套语义、只是换了身衣裳,第 14 章已经把地基打透。

往大一点想:学完 CMake,把 compile_flags.txt 扔了 ​

compile_flags.txt 的毛病是:它整个目录共用一份 flags。单文件、小工程够用;可一旦你有几十个 .c、每个 #include 的目录不一样、-std 还要分文件调,手写就管不过来了。

第 13 章学完 CMake 之后,你可以把 compile_flags.txt 扔掉、换成一个更聪明的东西:compile_commands.json。CMake 加一行 set(CMAKE_EXPORT_COMPILE_COMMANDS ON) 就能产出它,里面每个 .c 一份精确的完整编译命令(连 -I、-std、-D 全有),clangd 读它,就精确到「每个文件用各自正确的 flags」——再也不会有「整个目录共用一套 flags 不够用」的窘境。这一章先用手写的 compile_flags.txt 入门,把「clangd 靠 flags 工作」这件事吃透;第 13 章再升级到自动化,顺带阶段 4 第 5 章会把 compile_commands.json 还能干嘛(clang-tidy 也吃它)讲深。

小结 ​

到这一步,VSCode 这头就接通了。你带走的应该是这条认知:IDE 不是另一个世界,是你命令行那套工具链的一个视图——clangd 读的就是你 gcc 用的那套 -std/-I/-Wall,漏一个它就静默变瞎,所以视图画歪了别在 VSCode 里找原因,先回去对 compile_flags.txt 和你命令行的编译命令。具体到怎么用:工程根目录放一份 compile_flags.txt(每行一个 flag)、VSCode 装 clangd 扩展(语言服务让它管、调试借微软 C/C++ 的 cppdbg)、再配最小的 tasks.json 把编译包成 Ctrl+Shift+B、launch.json 把 gdb 接到 F5。这套搭起来,你写 C 的手感就从「命令行 + 文本编辑器」升到了「点一下就跳转、敲半个就补全、写错就画红线」;但底层跑的还是你第 1 章体检过的那套 gcc/clang/gdb——没变过。

参考资源 ​

  • clangd 官方:clangd.llvm.org —— 配置、--check 模式、扩展安装指引
  • compile_commands.json / compile_flags.txt 格式:clangd 官方文档「Configuring the compile commands」一节,讲两种 flags 来源的区别和适用场景
  • VSCode clangd 扩展:marketplace 搜 llvm.clangd,README 里有它和微软 C/C++ 扩展(IntelliSense 冲突)的共存说明
  • 承接章节:第 1 章(工具链体检,本机工具链可用);第 13 章(CMake 入门,compile_commands.json 替掉手写);第 14、15 章(GDB 基础与进阶,launch.json 底层接的调试器);第 18 章(格式化与质量门,clangd 的 format-on-save 接的就是那个 .clang-format)