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 章体检到的工具链同源):

终端
$ 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 章那条纪律):

终端
$ 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,每行一个:

终端
-std=c11
-Wall
-Wextra
-Iinclude

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

终端
$ 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,您看对比:

终端
$ 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,就是咱们命令行里 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 章再升级到自动化,后面工程化那一卷讲 CMake 工程化的一章,还会把 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)

87bb5f2 · 87bb5f2 · 2026-09-21