Skip to content

命令解析 ​

背景 ​

C++ 语言服务器需要知道如何编译项目中的每个文件。这些信息来自编译数据库(CDB),通常是由构建系统生成的 compile_commands.json 文件。CDB 中的每条记录都包含源文件路径和编译命令,例如:

bash
g++ -std=c++20 -O2 -g -I../include -DNDEBUG -c src/foo.cpp

这条命令记录了构建系统在实际构建过程中调用编译器的方式。然而,语言服务器无法直接使用它,原因有三个。

第一,这是驱动级命令,而非前端命令。 上面的 g++ 是编译器驱动程序,负责选择正确的前端、链接器和标准库。语言服务器实际使用的是 Clang 前端(cc1),而从 g++ 转换到 cc1 涉及大量隐式处理,包括确定目标三元组、注入系统头文件搜索路径、设置默认语言标准等。这些信息都没有显式出现在 CDB 中,而是由编译器隐式提供。

第二,命令中包含与语义无关的选项。 -g 只影响代码生成,不影响语义分析——语言服务器不进行代码生成,因此用不到这类选项。同样,-c(编译模式)和 -o(输出文件)是构建产物相关的指令,对语言服务器没有意义。未经筛选就将它们传给前端会增加不必要的复杂度,甚至可能引发错误。

第三,大型项目中的命令高度冗余。 在拥有数万个源文件的项目中,绝大多数文件使用相同的编译器和语义选项,只有头文件包含路径和宏定义有所不同。如果不进行去重,每个文件都需要单独查询工具链,造成内存浪费并延长启动时间。

在这三个问题中,第一个问题对用户体验的影响最大:缺少隐式信息。当语言服务器无法正确获取系统头文件路径时,用户会遇到标准库头文件错误——#include <vector> 报告 "file not found",或者 GCC 内置类型特征被标记为未声明的标识符。在 clangd 的问题跟踪器中,这类问题一直是最常被报告的问题之一(clangd#1262、clangd#1691)。

clangd 的解决方案是使用 --query-driver 参数:用户手动指定需要查询的编译器,随后 clangd 查询这些编译器以获取系统路径。这种方式有两个问题。首先,它需要手动配置——用户必须知道项目使用的是哪个编译器,并正确配置 glob 模式。其次,该参数无法独立发挥作用——它依赖 CDB 中已有的命令来触发查询(clangd#1219)。在交叉编译和嵌入式开发场景中,用户往往需要反复调试配置,clangd 才能正确识别工具链。

clice 实现了整个命令处理流程的自动化:从 CDB 读取命令后,它会自动识别编译器家族(GCC、Clang、MSVC 等)、自动查询工具链,并通过多级去重最大限度地降低启动开销。用户无需手动配置任何工具链相关参数。

设计 ​

命令处理的核心任务是将 CDB 中的原始驱动命令转换为可供 Clang 前端使用的 cc1 参数。这个转换过程涉及四个概念层:参数分类、命令分离、工具链查询和搜索路径提取。

参数分类 ​

加载 CDB 时,每个编译选项要么被排除在命令之外,要么保留在命令中、归入六类之一。被排除的是只有构建才读取的选项,否则它们会让编译方式相同的命令变得彼此不同:

  • 构建产物:输出文件(-o)、编译模式(-c)、依赖文件(-M 系列,以及 -MJ)、耗时记录(-ftime-trace)、中间文件(-save-temps)、序列化诊断、优化记录、汇编器选项(-Wa,)、cl 的列表文件与输出(/Fa、/Fe、/FR、/sourceDependencies)、GCC 的模块映射与依赖扫描输出(-fmodule-mapper=、-fdeps-file=)、cl 的模块标志(表明单元属于哪一种的 /interface 和 /internalPartition,这一点单元的模块声明已经说明;以及单元写出和读取的接口文件:/ifcOutput、/reference、/headerUnit)、nvcc 自己写法的输出文件与依赖文件、驱动程序本身针对该输入会忽略的选项,还有只有 GCC 才读取的选项:GCC 命令里 clang 不认识的警告(-Wlogical-op)和 LTO 并行任务数(-flto=8)。

  • 代码生成:只影响后端的选项——帧指针(-fomit-frame-pointer)、unwind 表(unwind tables)、函数与数据分段(-ffunction-sections)、调试信息(-g 系列)等。它们不会改变 AST、诊断输出或工具链查询结果。

    注意:-O、-fPIC、-fstack-protector、-fsanitize= 和 -flto 虽然看似与代码生成有关,但不属于此类。-O 会定义 __OPTIMIZE__ 宏,-fPIC 和 -fstack-protector 会定义 __PIC__ 和 __SSP__,-fsanitize=address 会影响 __has_feature(address_sanitizer):它们会改变预处理器状态,因此属于语义选项。-flto 也属于语义选项,因为驱动程序只在有它时才接受 -fsanitize=cfi 和 -fwhole-program-vtables。

其余选项保留在命令中:

  • 预编译:构建的预编译文件,clice 会根据磁盘上的文件自行构建它们:命令读取的预编译头文件(-include-pch)、命令是否写出预编译头文件(-emit-pch,以及它的 -o——输出中只保留这一个,用来找到写出该头文件的条目),以及命令是否指定了模块输出(-fmodule-output,不含路径,因为它决定了模块预编译写出完整 BMI 还是精简 BMI)。它们参与构成命令标识,但从不传给任何编译。

  • 诊断:警告控制选项(-Wall、-Wno-*、-Werror)。它们会改变发出哪些诊断,但不会影响 AST 或工具链查询结果。

  • 用户内容:可能因文件而异、但不影响工具链查询结果的选项。包括包含路径(-I、-isystem、-iquote、-idirafter)、宏定义(-D、-U)和强制包含(-include、-imacros)。它们表达的是“这个特定文件还需要什么”。

  • 语义:其余可识别的选项——它们会影响编译语义,并在工具链查询中发挥作用。例如 -std=c++20、-target、-march= 等。

  • 输入:源文件本身,它在解析后的命令中占据一个明确的槽位,而非众多普通字符串中的一个。

  • 未知:解析器无法识别的选项(例如,比 clice 内嵌 LLVM 更新的编译器所提供的选项)。它们会参与构成命令标识,但来自 CDB 的未知 Token 不会渲染到 clice 执行的编译命令中;用户在配置规则中写入的未知 Token 则会保留。

如果数据库中几乎每个条目最终仍各自得到一条独立的命令,彼此只差在用户内容之外某一个选项的值上——即每个翻译单元各自的某个输出,而 clice 不知道应当把它排除在外——加载时就会在日志中写出这个选项。

分类基于 Clang 自身的选项表(OptTable),使用选项 ID 而非字符串匹配。

结构化命令 ​

分类完成后,每条命令只解析一次,形成结构化命令(Command):一个由已分类参数组成的驻留序列,其中输入文件占据明确的槽位。CommandTable 保存 clice 知道的每一条命令——数据库中的条目、手工编写的命令以及应用规则后得到的命令——每条只存一份,由稳定的 CommandID 标识;字符串也会被驻留,以便通过稳定的指针进行比较。所有下游处理——工具链查询、渲染、规则和标识——都使用这种结构化形式;不会重新解析命令字符串。

有两个重要的派生视图:

  • 渲染:同一条结构化命令可以按需渲染成编译器驱动程序命令行(用于查询,或向代理提供可运行的命令),也可以与查询结果组合成前端参数。编译器驱动程序命令行会按命令原本的写法给出每个选项:GCC 只认它自己的选项名,而这个名字不一定是 clang 的(-msmall-data-limit=8 在 clang 里是 -G 8,RISC-V GCC 不接受后者)。
  • 命令哈希:命令保留的每个参数,连同输入文件的槽位位置和工作目录,会共同哈希为它的命令哈希——这是用于 CDB 差异比较、每个翻译单元的索引所记录的命令以及上下文选择的稳定标识。

这种分类还能提高工具链查询的缓存效率。查询需要实际调用编译器驱动程序(g++ -E -dM -v),耗时从几毫秒到一百多毫秒不等。查询结果只取决于驱动程序和与查询相关的选项——用户内容选项(-I、-D)不会影响驱动程序输出的系统路径或目标三元组。因此,即使各文件的 -I 路径不同,只要查询相关视图相同,就会共用同一份查询结果。在实际项目中,上万个文件通常会归并为几十个不同的查询键。

编译数据库 ​

CompilationDatabase 保存每个已加载来源的条目——来源即由配置注册或在工作区中发现的一份 compile_commands.json。每个来源独立加载、重新加载和卸载;它的条目解析后存入 CommandTable,并保持文件内的原有顺序,因为生成器输出同一文件的多个条目时会遵循固定的配置顺序。如果多个条目的命令只在各自的源文件,以及每条命令都会排除的部分(目标文件、依赖文件、-frandom-seed)上不同,它们只解析一次:一个 target 的一万个翻译单元只需解析一次,而不是一万次。数据库只存事实:它不决定一个文件的哪个条目胜出。

手工编写的命令——规则的 default_command、内置的兜底命令——与条目经过同一套规范化流程(Normalizer),并在末尾合成输入槽位,因此声明的命令在查询、编辑和渲染方面与数据库条目完全一致。

规则与成员 ​

Rules 是配置中 [[rules]] 的唯一读者,作用于当前生效的构建配置:一个文件匹配哪些规则,它从哪些数据库取得命令、按什么顺序,这些规则做哪些编辑,它是否参与索引、Lint 和格式化,以及哪条默认命令涵盖它。项目的成员则是构建在这些规则之下要编译的内容——它是配置、数据库以及被记录为临时成员的那些文件的函数,对服务器和每个 CLI 入口都一样(clice index、clice lint、clice inspect 打开项目的方式完全相同)。所有使用方——命令解析、依赖扫描、后台索引、上下文协议——都向项目询问,而不是向数据库询问:

  • 条目。 文件在数据库中的条目按构建顺序排列:先是匹配该文件的规则所带的来源,再是其他生效规则的来源,二者均按声明顺序排列,发现得到的来源排在最后;同一来源内则按文件中的顺序排列。第一个条目是默认选择;用户的选择(clice/switchContext)可以选用其他条目。条目不会因为某个模式未涵盖其文件而消失——规则只决定优先级。
  • 编辑。 每条匹配且生效的规则的 remove 与 append 列表,按声明顺序应用——同一条规则先删后加,靠后的 remove 能作用于靠前规则添加的内容。追加的标志排在命令的所有标志之后,即便数据库把某个标志写在文件之后也是如此,因此追加的 -std 总会生效。一个文件从另一个文件那里拿到的命令——头文件来自它的宿主,文件来自它所借用的翻译单元——会经过匹配其中任一文件的规则编辑,每条规则只算一次,按声明顺序应用,因此头文件看到的宏与宿主编译时一致。从一个借来命令的文件那里再次借来的命令,仍把最初提供它的翻译单元记为来源:只应用该翻译单元和接收方的规则,中间任何文件的规则都不应用。
  • 命令。 文件用它的条目所带的命令编译;没有条目时,则使用第一条匹配且声明了 default_command 的规则所给出的命令,或者临时成员的命令。以上都没有的文件使用内置命令,其驱动程序取决于 clang 根据扩展名判定的语言(clang++ -std=c++20 用于所有 C++ 扩展名形式——其中包括其他编译器和构建系统为模块单元采用、clang 却不认识的扩展名(.ixx、.mxx、.mpp)——以及含义不明的 .h,-x cuda --cuda-device-only 用于 CUDA,其余使用 clang)。
  • 成员。 构建中的翻译单元:先是有条目的文件,再是磁盘上被某条 default_command 规则的模式涵盖的源文件(从模式指定的目录中枚举得到,头文件从不计入),最后是临时成员。依赖扫描会运行每个成员的每一条命令,因此即使某个头文件只能通过某个文件的一个条目到达,该文件仍会出现在它的候选宿主之中。数据库列出的头文件与任何有条目的文件一样是成员,会作为独立的翻译单元建立索引,与包含它的源文件并列。后台索引会接纳成员,除非有匹配的规则写明 index = false;这项检查位于索引队列处,因此每条将工作入队的路径——启动、数据库重新加载、保存——都会遵守它。

宿主 ​

没有自身命令的头文件,会作为包含它的某个翻译单元的一部分参与编译。宿主层会在构建所编译、且语言与该头文件相容的包含者中排序——.h 可以属于任何语言,.hpp 属于 C++ 及建立在其上的语言(Objective-C++、CUDA),.cuh 只属于 CUDA,因此 C++ 头文件永远不会按 C 编译:条目来自该头文件自身规则所指定数据库的翻译单元排在最前,其次是文件名(不含扩展名)与头文件相同的翻译单元,再次是同目录下的翻译单元,最后按路径远近排列。在建立索引时的编译中为该头文件贡献过索引数据的翻译单元也会加入候选。其中第一个编译时会进入该头文件的(依据该翻译单元的包含树判断,参见编译上下文),就是它的默认宿主。不是构建成员的文件永远不会成为宿主,写出预编译头的条目也不会。

发现 ​

当没有任何规则声明来源时,构建的数据库就是在工作区中找到的那些 compile_commands.json:启动时取根目录及其直接子目录中的,之后每当打开一个没有条目的文件,再取从该文件所在目录向上直到根目录的各级目录中的——位于目录树更深处的项目,会在它的某个文件第一次被打开时加载,除此之外不会主动扫描。批处理命令(clice index、lint、format、scan)不打开任何文件,它们取根目录及其直接子目录中的数据库(index 和 lint 还会加上之前某次会话加载过、由索引记住的那些);一份都没有时,它们和服务器都会列出所跳过的、位于根目录以下三层以内的数据库,以及能加载它们的规则。链接到另一份同样被找到的数据库的 compile_commands.json 算作同一份数据库,例如为 clangd 做配置时会把 build/compile_commands.json 链接到根目录。发现得到的数据库排在声明的数据库之后,层级浅的排在层级深的之前,再按路径排序;被其中多份列出的文件默认按第一份编译,其余作为候选提供;只被靠后的某份数据库列出的文件,则由它提供命令。发现不止一份时,启动阶段会提示一次,并说明改用带标签的规则可以把它们变成可切换的配置。服务器会在每次轮询时继续发现,因此启动之后才生成的数据库——无论是在根目录还是在新建的子目录中——一出现就会被加载。已发现的数据库消失后,它的条目仍然继续生效,但会让位于现存的数据库:build/ 目录被重新生成为 out/ 时,两者共有的文件会立刻改由 out/ 提供,而等它回来时再交还给它。

推断 ​

既没有条目也没有宿主、也没有匹配的规则声明 default_command 的文件,会借用附近一个同语言的翻译单元的命令——.h 与任何语言相容,.c 从不借用 C++ 命令,.cpp 也从不借用 C 命令;C++ 源文件与 C++ 模块单元则可以互相借用,因此在一个由 .cpp 翻译单元组成的项目里,第一个模块接口会按这些翻译单元的标志编译。所借用的翻译单元优先取该文件所在目录中的,其中文件名(不含扩展名)相同的优先,其次按名称取第一个;其次,对头文件而言,取头文件搜索目录(-I、-isystem、-iquote)包含它的翻译单元,目录越近越优先——该翻译单元自身的代码正是通过这条路径找到这个头文件的,因此它的命令也正是这个头文件所面向的命令;最后取路径最接近的翻译单元。借来的命令会同时带上两个文件的规则编辑,按声明顺序应用,并标记为 Borrowed:决策日志会写明命令来自哪个翻译单元,关于文件缺失的诊断会附带一条引导说明,而该文件仍处于构建之外——头文件始终如此,源文件则直到用户打开或保存它为止;clice inspect 也用同样的方式解析它。构建之外的文件也可以借用临时成员借来的命令,这条命令仍是它最初所来自的那个翻译单元的命令;成员本身只向构建所声明的翻译单元借用命令,因此没有哪个成员的命令建立在另一个成员的命令之上。

临时成员 ​

用户在编辑器中打开或保存的项目源文件(位于构建目录树、缓存、隐藏目录以及自成项目的子目录之外),如果没有任何数据库列出它、也没有任何规则涵盖它——通常是数据库生成之后才新建的文件,或是根本没有数据库的项目中的文件——就会被记录为临时成员:只要没有任何翻译单元包含它,它就是构建的成员(作为 unity build 一部分的文件仍在包含它的翻译单元的上下文中编译),使用它从附近某个翻译单元借来的命令,借不到时则使用内置命令。它像其他翻译单元一样被扫描,因此它的模块声明会向导入方提供该模块,它包含的头文件也能以它为宿主——在只有一个 main.cpp、没有数据库的项目里,main.cpp 就是它所包含的标准库头文件的宿主;后台索引会覆盖它。每当构建的命令发生变化——数据库重新加载、有文件被记录——都会重新检查它的命令和包含者,该文件随之加入构建、更换命令或离开构建,与数据库条目的行为一致;仅靠一次普通保存增删的 include,要等到下一次这类变化或重启时才计入。

记录保存在该配置的索引数据库中,重启后依然有效。一旦有数据库列出该文件,或有规则涵盖它,就由它们接管,记录随之删除;如果数据库删去了该文件原有的条目,该文件会留在构建之外,直到再次被保存。被删除的临时成员会保留记录,就像消失的翻译单元会保留条目一样,因此文件回来时——比如切换分支之后——会立刻成为成员;只有重启才会忘掉已经不存在的文件。从未写入磁盘的缓冲区不会加入构建:加入构建的只有磁盘上的内容。

合成 ​

文件的最终命令从上述各层中选出,共六级,按固定顺序依次尝试:优先采用用户在编辑器中为该文件选择的宿主,前提是该宿主的编译仍在所选的位置进入该文件;否则采用该文件自身的命令,前提是它是一个翻译单元(所选的条目,否则是它的第一个条目;规则涵盖的源文件所用的 default_command;或者临时成员的命令);否则——对头文件而言——采用排名第一的宿主;否则采用第一条匹配规则的 default_command;否则采用它从附近某个成员借来的命令(推断);最后是内置命令。每一级给出的都是一个候选,并写明它是哪个文件的命令——文件自身的命令不写,头文件的命令写宿主,借来的命令写它所来自的翻译单元——随后叠加该文件以及这些文件的规则编辑,最后加上本次运行的额外参数(Lint 方案带来的 clang-tidy 参数)。选出的命令再经渲染:工具链把它转换成前端参数,并带上头文件所需的包含方上下文(参见编译上下文)。已找到宿主的头文件会沿用该宿主的命令,即使宿主的包含树仍在获取之中,或者它所需的包含方上下文无法跟踪——此时就不带该上下文编译,文件上的一条警告会说明这一点。对条目或宿主某条命令的选择,记下的是数据库或规则所写的原始命令,因此规则的编辑不会让选择失效。选择作用于编辑器发起的编译,以及带 --host 的 clice inspect 运行;后台编译不带选择进行解析,因此索引看到的是构建自身的答案。

模式针对绝对路径匹配:相对模式锚定在配置文件所在的目录(含 .. 路径段),通过 initializationOptions 传入的规则则锚定在工作区根目录;绝对模式或以 ** 开头的模式按原样匹配。带 configuration 标签的规则只在该标签生效时适用;不同的标签构成配置菜单,启动时按 --configuration、持久化的选择、default_configuration 的顺序决定哪个配置生效(参见编译上下文)。只要有任何规则声明了来源(一份数据库或一条 default_command),发现流程就会关闭:声明即代表全部意图,不会再采用工作区根目录中的数据库。只有完全没有声明任何来源的配置才会回退到发现。

配置粒度在整个流水线中保持不变:依赖扫描的搜索路径提取按实际生效的命令进行(不同的 -I 集合产生不同的搜索配置),而工具链查询会进一步去重,因为与用户内容有关的选项不会影响查询结果。

工具链 ​

Toolchain 将驱动级命令转换为 cc1 参数:它按命令的编译器家族所要求的方式查询驱动程序(每种编译器各占 src/command/toolchains/ 下的一个文件),并缓存得到的回答。

编译器家族。 命令的编译器家族在该命令规范化时从可执行文件名读出——CompilerFamily 枚举包括 GCC、Clang、MSVC、ClangCL、NVCC、Intel 和 Zig。识别逻辑可处理多种命名变体:版本后缀(clang++-17)、架构前缀(arm-none-eabi-g++)以及 Windows 的 .exe 后缀。名称只用来认出使用另一套命令行语法的驱动程序:cl 和 clang-cl、nvcc,以及由两个词组成的 zig 驱动程序。一个 GCC 风格的驱动程序底层究竟是 GCC 还是 clang,由它自己对查询的回答判断,从不看名称:/usr/bin/c++ 在 macOS 上是 clang,emcc 和 zig cc 也是 clang。

缓存策略。 缓存分为两层。查询层缓存每次查询的任务所设置的前端,其中已去掉查询自身的输入和 clice 前端无法接受的部分;它以命令中与查询相关的结构为键(驱动程序、与查询相关的标志、输入类型——.c 和 .cpp 可能触发不同的驱动规则;如果命令对工作目录敏感,工作目录也会纳入键中)。合成层按输入类型,在其上加入每条命令自身的用户内容,供命令渲染使用。失败的查询也会被缓存(负缓存),但暂时性失败会在冷却期后重试,而不会被永久记住。

搜索路径 ​

SearchConfig 从 cc1 参数中提取头文件搜索路径,并将其组织为四层结构:

  1. 引号(-iquote):#include "foo.h" 的搜索路径
  2. 尖括号(-I):#include <foo.h> 的搜索路径
  3. 系统(-isystem、-internal-isystem 等):系统头文件路径
  4. 后置(-idirafter):在系统目录之后搜索的路径

该四层模型与 Clang 的内部搜索布局相对应。各层中的路径会被去重(从尖括号层开始),去重算法复现了 Clang 的行为:如果同一路径同时出现在尖括号层和系统层,则保留尖括号层中的路径。这可以确保 #include_next 的正确性。

SearchConfig 是包含路径补全、包含路径解析、依赖图构建及其他功能的基础输入。

实现 ​

加载与解析 ​

CDB 加载使用 simdjson 进行流式 JSON 解析,逐条处理记录:

  1. 读取每条记录的 directory、file 和 arguments(或 command)字段
  2. 根据驱动模式展开响应文件(@file),并可处理 UTF-16 编码文件和嵌套响应文件
  3. 将 NVCC 命令转换为等效的 clang CUDA 调用:nvcc 的选项由它自己的一张选项表读取,每个选项的长写法和短写法都能识别;nvcc 交给宿主编译器的内容(-Xcompiler)按该编译器拆分命令行的方式拆分:宿主编译器是 -ccbin 所指定的编译器,没有指定时 Windows 上是 cl,其他平台上是 GCC。宿主为 cl 时,这些标志读作 cl 的选项;宿主为 GCC 时,clang 不认识的警告选项会被去掉,与 GCC 命令中的处理相同
  4. 过滤非 C/C++ 文件(例如 .rc、.asm、.def)
  5. 将相对文件路径解析为绝对路径
  6. 将每个选项解析、分类一次并存入结构化命令,同时以 directory 为基准将相对包含路径转换为绝对路径。clang 的选项表不认识、但编译器认识的写法,由一张记录该编译器自身写法的表读取:读作它所表示的 clang 选项(Intel 的 -qopenmp、/Qstd:、/fsycl),或者在只有构建才读取它时去掉(GCC 的 -fmodule-mapper=、cl 的 /ifcOutput)
  7. 将相同的命令去重,使其共享 CommandID

在 Cygwin 或 MSYS2 内部写出的数据库(由在它们的 shell 中运行的 CMake 或类似的工具写出)按 POSIX 风格书写路径:/cygdrive/c/proj 或 /c/proj,编译器则写作 /usr/bin/c++.exe。在 Windows 上,写出这些路径的 Cygwin 或 MSYS2 运行时用它的挂载表(mount table)把它们映射为 Windows 路径,包括条目的目录和文件、它的编译器,以及它的路径选项的值。这个运行时是 PATH 上第一个满足以下条件的运行时:它的挂载表能把首个此类条目的目录映射到实际存在的文件,该条目的编译器若也按这种风格书写,同样要映射到实际存在的文件。其他运行时的挂载表会把该目录映射到各自的根目录之下;Git for Windows 的 MSYS2 对盘符路径的映射虽与独立安装的 MSYS2 相同,却没有后者的 /usr/bin/c++.exe。这种数据库的 command 字符串按 sh 的规则拆分。如果 PATH 上没有运行时能映射该数据库,clice 不读取它,并提示用户把正确的运行时加入其中。

-Xclang 传递的内容按 cc1 的选项读取:编译从不采用的选项会被去掉,与它的驱动程序写法一样;CMake 直接传给 cc1 的预编译头文件也会被识别:翻译单元的 -Xclang -include-pch -Xclang <pchfile>,以及构建该 PCH 的条目中的 -Xclang -emit-pch,都会成为结构化选项,任何编译都不会把它们渲染到命令中。磁盘上的 PCH 可能出自其他编译器,因此 clice 会用写出它的那个条目的命令自行构建一份(在 CMake 中即 cmake_pch.hxx.cxx 的条目;GCC 在强制包含的头文件旁写出的 .gch 同样能用来找到该条目),读取该 PCH 的每个翻译单元都改为加载 clice 构建的版本:打开文件的 Preamble PCH 以链式 PCH 的方式接在它之后,后台索引也在它之上解析。PCH 所含的头文件单独打开时,编译不使用该 PCH:否则 PCH 中的头文件保护会跳过该头文件自身的正文。与编译借以进入头文件的其他强制包含一样,PCH 所代表的那个强制包含的头文件也会从命令中去掉(见编译上下文)。

工具链查询 ​

不同编译器家族使用不同的查询策略,每种策略各占 src/command/toolchains/ 下的一个文件:

GCC 风格的驱动程序(gcc、clang、Apple clang、zig、emcc、交叉编译与裸机 GCC):只询问驱动程序一次,让它带着命令自身的标志,以输入文件的语言预处理一个空文件,同时输出详细信息并打印宏(-E -dM -v)。这一次的回答就包含了 clice 需要的一切:

  • 驱动程序运行的任务(job)。clang 的任务原样就是 clice 要用的 cc1 命令,再加上驱动程序打印的头文件搜索列表中任务没有写出的目录:比 clice 所用版本更老的 clang 会在自己的前端里设置某些目标的一部分搜索列表——clang 21 之前 Darwin 的 framework 目录(Xcode 26 之前的 Apple clang),16 之前 FreeBSD 的全部搜索列表,21 之前 Cygwin 的,23 之前 Hexagon 的——而 clice 的前端把这部分交给驱动程序设置。这些目录排在任务自己的目录之后,与那个前端添加它们的位置一致。GCC 的任务则带有 GCC 的目标、它的头文件搜索列表,以及 GCC 驱动根据自身配置和 specs 添加的选项(目标默认值如 -march=armv7-a+fp -mthumb,宏如 -D_REENTRANT,加固选项如 -fstack-protector-strong)。随后由 Clang 自己的驱动构建 cc1 命令:固定为该目标,不带 Clang 自己的任何系统头文件(-nostdinc),并加上这些选项和命令自身的标志;GCC 的搜索列表按 GCC 的顺序排在后面,其中 clang 的驱动程序对该目标按 framework 目录搜索的目录,同样按 framework 目录搜索(macOS 上的 GCC 把 SDK 的 System/Library/Frameworks 列为普通目录),clang 的内置头文件紧挨在 GCC 的私有目录(lib/gcc/<target>/<version>/include)之前,遮蔽该目录。这个目录里既有 GCC 版本的 clang 内置头文件(clang 无法解析),也有只有 GCC 才有的头文件(omp.h、quadmath.h、厂商的 intrinsics 头文件)。clice 编译时看不到该目录中 clang 也有的头文件,所以其余头文件仍能在那里找到,clang 自己的 stdatomic.h 也无法经由 #include_next 进入 GCC 的版本。列表更靠后的位置若还有这类头文件的另一份副本,而 GCC 自己的那份并不 #include_next 到它,GCC 就永远读不到它,clice 编译时同样看不到:例如排在 GCC 版本之后的 newlib 的 stdatomic.h。编译看不到的文件也不进入 clice 自己的 include 搜索:依赖关系、#include 补全和文档链接都不会用到它们。
  • 语言标准,从 __cplusplus 或 __STDC_VERSION__ 读出,命令没有指定时用它补上 -std:GCC 15 默认按 C23 编译 C,Apple clang 默认按 C++14 编译 C++。

询问时带着命令自身的标志,并按命令原本的写法给出,所以驱动程序回答的就是这条命令,而 GCC 只在这次编译成功时才会给出回答:关闭某项默认设置的标志(-fno-stack-protector)、--sysroot 或 --specs 文件都会体现在回答中。询问失败时,日志会写出它的报错和 clice 运行的命令。clang 不认识的 CPU 和 ABI 名称(GCC 的 -mtune=intel、Darwin 上的 -mabi=lp64)会从 cc1 命令中去掉,GCC 的双核写法 -mcpu=cortex-a72.cortex-a53 只保留第一个核。RISC-V 的 -march 会去掉 LLVM 不认识的扩展(WCH 的 _xw)和它不认识的版本(较老 GCC 的 i2p0):否则 clang 会丢掉整个字符串,连同所有特性宏。通用构建(-arch arm64 -arch x86_64)按其中第一个架构读取。

Cygwin 和 MSYS2 编译器:Windows 上的这类编译器(Cygwin 和 MSYS2 自带的 GCC,以及基于 Cygwin 构建的工具链,例如 Andes 的 RISC-V GCC)像任何 GCC 风格的驱动程序一样作答,只是给出的是 POSIX 路径(/usr/include、/cygdrive/c/...),clice 的 clang 无法打开。这些路径由驱动程序加载的运行时用其挂载表映射,每次查询都从该运行时自己的 mount 读取挂载表。在驱动程序旁边和 PATH 上的运行时(cygwin1.dll、msys-2.0.dll)中,按 Windows 查找程序 DLL 的顺序,取第一个能把驱动程序所跑作业的程序映射到实际存在的文件的那个:只取第一个运行时的话,若 Git for Windows 的 MSYS2 在 PATH 上排在工具链所加载的、位于其外的 Cygwin 之前,就会选错。假定一套映射会出错:Cygwin 把 /usr/lib 挂载在 <root>/lib,MSYS2 把驱动器挂载在 /c 这样的路径上,用户的 /etc/fstab 还会加上自己的挂载。驱动程序本身按 Cygwin 的方式查找:名称可以不带 .exe,也可以经由 Cygwin 的符号链接找到(CMake 记录的是 /usr/bin/cc,它是指向 gcc.exe 的链接)。这样的编译器只有在其运行时的 bin 目录位于 PATH 中时才能启动;否则查询会失败,错误信息会说明这一点,编辑器设置介绍了如何在各个编辑器中设置它。

MSVC / ClangCL:先让 cl 或 clang-cl 预处理(/EP)一个写着 _MSVC_LANG 和 _MSC_FULL_VER 的文件,只问一次。由此得知它编译所用的 C++ 标准,因为 /std:c++latest 的含义随版本而变;还得知 cl 的版本,因为 clang 自己的探测会取已安装的最新工具集。随后由处于 MSVC 兼容模式(--driver-mode=cl)的 Clang 驱动构建 cc1 命令,使用这个标准,并把 cl 的版本作为 -fms-compatibility-version。clang-cl 的版本则是同一套探测从它的参数所选的工具集(/winsysroot)中得出的版本。cl 只会收到命令里的 /std::其余参数是按 clang 的 cl 模式写的,cl 会拒绝;命令用 clang 写法设定的标准或版本(例如规则追加的 -std=c++23)仍以 clang 的读法为准。位于某个工具集里的 cl.exe(<toolset>/bin/Hostx64/x64/cl.exe)用这个工具集的头文件编译:Clang 驱动会被告知这个工具集(/vctoolsdir),否则它自己的探测会取已安装的最新工具集。在开发者命令行里,则以它设置的 INCLUDE 列出的构建所用头文件为准。

nvcc:nvcc 的 dry run 会给出 CUDA 根目录、宿主编译器、nvcc 定义的宏,以及它交给宿主编译器的头文件目录(工具包的 include,以及 CUDA 13 的 include/cccl,thrust、CUB 和 libcu++ 都在那里)。宿主编译器按 GCC 风格驱动程序的方式询问,使用输入文件的语言,带上命令的 --sysroot,但不带命令的其他标志:GCC 宿主编译器像上文那样固定目标和搜索列表,clang 宿主编译器则什么都不需要。随后由 Clang 驱动带上 nvcc 的宏构建 cc1 命令,输入为 CUDA 文件时使用 CUDA 模式;nvcc 的头文件目录排在命令自己的目录之后、宿主编译器的目录之前,与 nvcc 自己的宿主编译命令一致。宿主编译器为 cl 时(这是 nvcc 在 Windows 上的默认设置),dry run 运行时会把 cl 所在的目录放到 PATH 上,因为 nvcc 只在那里查找 cl:该目录是 -ccbin 指定的目录;命令没有指定、开发者命令行也没有把 cl 放到 PATH 上时,则是 Visual Studio 安装的最新工具集的目录。dry run 输出中 cudafe++ 的那一行给出 cl 的 C++ 方言和版本,随后由 cl 模式下的 Clang 驱动构建 cc1 命令,nvcc 交给 cl 的 /EHsc 排在命令自身的标志之前。

clang 理解不同的标志:GCC、cl 或 nvcc 当作错误的警告,在 clice 里仍是警告:-Werror 和 /WX 去掉,-Werror=<group> 改为 -W<group>。clice 的 clang 会报出这些编译器不报的警告,而它们的构建从不把这些当作错误。GCC 的 -fmodules 也会去掉:它开启的是 GCC 的 C++20 模块,clang 的 C++20 本来就有,而 clang 自己的 -fmodules 意味着它的头文件模块。clang 的命令则原样保留这两者。

clice 不运行的编译器:规则写上 query_toolchain = false,clice 就不运行它所匹配文件的编译器——用于本机上没有的编译器(在容器里或另一台机器上写出的数据库),或是不该运行的编译器。此时改由 Clang 自己的驱动构建 cc1 命令,就像一个以该编译器名字安装的 clang 那样:g++ 按 C++ 编译,前缀所指的架构若是 clang 认识的(aarch64-linux-gnu-g++ 是,riscv-none-elf-gcc 不是),这个前缀就是目标,除非命令自己指定了目标。GCC 自己的写法按 clang 能接受的形式交给它(-mcpu=cortex-a72.cortex-a53 只取第一个核,RISC-V 的 ISA 字符串去掉 LLVM 不认识的扩展),指定了 clang 的目标不认识的 CPU 或 ABI 的选项(AArch64 上的 -mabi=lp64)则去掉。其余一切——标准库、系统头文件、默认标准——都取 clang 对该目标的默认值。询问失败的编译器也按同样的方式读取,用它编译的每个文件都会在开头显示询问的报错(toolchain-query-failed);如果 clang 自己的驱动也读不了这条命令,文件显示的则是 clang 的报错。

外部驱动的版本可能比 clice 内嵌的 LLVM 版本更新,其 cc1 输出中可能包含 clice 无法识别的选项。解析时会静默丢弃未知选项,以保证兼容性。

查询完成后,会从结果中移除临时查询文件的路径和与模块输出相关的标志(它们引用了已删除的临时文件)。如果 clice 的资源目录与查询返回的不一致,会替换所有相关路径,确保前端使用匹配版本的内置头文件。任务自身的内置头文件目录则保留下来,紧跟在 clice 的目录之后,像 GCC 的私有目录那样被遮蔽:只有那个 clang 才有的头文件(libomp 安装在那里的 omp.h、compiler-rt 的 xray/、Apple clang 的 ptrcheck.h)仍能在那里找到。命令的搜索路径指向的其他 clang 内置头文件目录(另一个 clang 的 -isystem <clang>/lib/clang/<version>/include)则会被替换。

启动预热。 在服务器启动的依赖扫描阶段,会收集所有唯一的工具链缓存键并并行查询。查询子进程的管道排空和进程等待也会并发执行,以避免管道填满导致死锁。预热完成后,后续所有工具链查询都会命中缓存。

搜索路径提取 ​

工具链查询得到 cc1 参数后,搜索路径提取会遍历这些参数,按类型将 include 路径选项分入四个层级。所有路径都会解析为绝对路径并规范化(消除 . 和 ..)。System 层级内部的顺序与 clang 一致:-isystem 和 -iwithsysroot(在其绝对路径前拼接 sysroot)、-iframework、-iframeworkwithsysroot、-c-isystem(仅 C)、-cxx-isystem(C++ 与 Objective-C++)、-objc-isystem(仅 Objective-C)、-objcxx-isystem(仅 Objective-C++)、驱动程序自己的目录、驱动程序的 framework 目录。framework 目录(Angled 层级中的 -F;System 层级中的 -iframework 和驱动程序的 -internal-iframework)像 clang 那样,在第一个含有 Foo.framework 的 framework 目录里把 <Foo/Bar.h> 找成 Foo.framework/Headers/Bar.h,找不到时再找 Foo.framework/PrivateHeaders/Bar.h,clice 的依赖关系和它添加的 include 都按此查找;#include 补全会列出其中的 framework,进入某个 framework 后再列出它的 Headers/。

-iprefix / -iwithprefix / -iwithprefixbefore 三个选项必须按出现顺序配合处理:-iprefix 设置前缀,后续的 -iwithprefix 将前缀添加到其路径之前,并将结果放入 After 层级;-iwithprefixbefore 则将结果放入 Angled 层级。

四个层级拼接完成后,从 Angled 层级开始去重。Quoted 层级不参与去重——同一路径同时出现在 Quoted 和 Angled 中是合法的,两者都会保留。这复现了 Clang 的内部行为。

常见问题 ​

  • 为什么按选项 ID 分类,而不是字符串匹配?

    clice 的参数解析基于 Clang 自身的选项表(从 Options.inc 生成),使用选项 ID 进行分类。字符串匹配容易遗漏边界情况:Clang 的选项语法有多种形式——-std=c++20 是 joined 形式,-I /path 是 separate 形式,-Wall 是 flag 形式,有些选项还有 / 前缀(MSVC 风格)。按 ID 分类后,Clang 的解析器就能正确处理所有这些语法变体,分类逻辑只需要关心“这个选项是什么”,不需要关心“它是怎么拼写的”。

  • 为什么与用户内容相关的选项不参与工具链缓存键?

    这是分类设计的核心收益。-I 和 -D 不会改变编译器驱动输出的系统路径、目标三元组或语言默认设置。将它们排除在缓存键之外,使缓存键数量从“每个文件一个”降到“每种配置一个”。一个拥有数万个文件的项目通常只有几十个不同的缓存键,启动时只需要几十次子进程调用。

  • 为什么搜索路径去重必须精确匹配 Clang 的行为?

    如果语言服务器的头文件搜索顺序与实际编译器不一致,#include 可能解析到不同的文件——同名头文件存在于不同目录时,搜索顺序决定了使用哪一个。#include_next 的语义更是直接依赖搜索目录的去重结果。严格匹配确保语言服务器看到的代码与编译器完全一致。

  • 为什么即使是 GCC 命令,clice 也按 clang 来解析?

    标明编译器身份的预定义宏保持 clang 的值:无论项目由哪个 GCC 构建,__clang__ 都有定义,__GNUC__ 都是 4。照搬 GCC 的整套宏会让 clang 走进代码专为 GCC 保留的分支,那些分支用到的 GCC 专有内建函数和扩展 clang 无法解析;何况 GCC 的宏里有数百个与 clang 的只是写法不同。真正跟随实际编译器的,是描述这次构建、而不是描述编译器本身的一切:目标及其默认值、头文件搜索列表、语言标准,以及 GCC 的配置添加的宏。

  • 为什么让驱动程序做预处理,而不用 -###?

    一次运行就能回答所有问题:clang 的任务、GCC 的搜索列表和目标,以及标明默认语言标准的预定义宏,而默认语言标准在任何任务行里都看不到(它是编译器的默认值,不是一个标志)。驱动程序的名称分不清 clang 和 GCC,它的回答却能分清。

  • 为什么按命令中写的名称调用驱动程序,而不是用解析后的路径?

    编译器驱动的行为受调用名称影响。例如,/usr/bin/clang++ 通常是 /usr/lib/llvm-20/bin/clang 的符号链接,但以 clang++ 名义调用时会自动启用 C++ 模式并链接 C++ 库。如果在识别前用 realpath 解析到实际路径,会丢失调用名称携带的语义信息。类似地,如果 arm-none-eabi-g++ 被解析成某个通用 GCC 二进制的路径,交叉编译的上下文就会丢失。

  • 为什么对 Cygwin 编译器不把路径从 Windows 映射到 POSIX?

    编译器运行只是为了回答它如何编译,处理的是命令所用语言的一个空文件;而且 Cygwin 程序本身就接受 Windows 路径作为参数。clice 用自己的 clang 编译,它直接打开编辑器给出的 Windows 路径:clice 交给编译器的路径、clice 报告的诊断,都不经过 POSIX 一侧。只有编译器的回答和在 Cygwin 内部写出的数据库使用 POSIX 路径,这两者都会被映射。

  • 没有 CDB 条目的文件怎么处理?

    头文件会先通过依赖图寻找包含它的源文件,并借用该文件的命令(参见 编译上下文)。否则,由第一条带 default_command 的匹配规则提供命令——要描述所有文件共用同一套标志的项目,或是一个临时目录,用的就是这种方式。这些都没有的文件会借用附近翻译单元的命令(参见推断);只有连可借用的翻译单元也没有的文件才使用内置命令:按文件的语言选择 clang 或 clang++ -std=c++20,并注入资源目录(resource dir),这样基本的语义分析仍然可用,同时会有一条提示说明该命令是猜测得到的。在编辑器中打开或保存这样的源文件,会让它成为临时成员。

已知限制 ​

  • 发现流程从不扫描整棵目录树。 嵌套项目的数据库要等到它的某个文件被打开时才加载;在那之前,它的翻译单元不会被索引,批处理命令也看不到它。用一条规则指明这份数据库(或写明 default_command),就能从一开始覆盖它。

  • 只有编辑器才会把文件加入构建。 以其他方式出现在磁盘上的源文件——检出、在文件管理器中复制、由生成器产生——如果没有数据库列出它,会留在构建之外(不被索引、不提供模块、不作为头文件的宿主),直到它在编辑器中被打开或保存一次,或重新生成的数据库列出了它。临时成员按构建配置分别记录。

  • 不跟随头文件中的 Cygwin 符号链接。 Cygwin 以符号链接形式安装的头文件(例如 ncurses 的 ncurses.h,位于 Cygwin 的 /usr/include 中)只有 Cygwin 程序才会跟随:clice 的 clang 读到的是链接本身。clice 只对驱动程序跟随这种链接。

  • 部分编译器家族支持不完整。 对查询既不给出 clang 任务、也不给出 GCC 任务的驱动程序——Intel 的经典编译器 icc、其他厂商的编译器——会使用 clang 针对当前机器的默认设置,工具链错误会说明这一点。NVCC 已有专门的查询逻辑(解析 nvcc --dryrun 输出并将其转换为 clang CUDA 调用),多架构命令则只解析最新的架构。

  • 只有 GCC 接受的语言特性按 clang 的理解解析。 只有 GCC 能编译的代码——GCC 专有的内建函数和扩展、在 clang 不支持它的目标上使用 __float128、嵌套函数——会显示 clang 的报错;只有 GCC 认识的 CPU 名称会丢失其特性对应的宏。

  • CUDA 按 clang 的 CUDA 理解解析。 只有 nvcc 能编译的代码会显示 clang 的报错:nvcc 12.8 的原子内建函数(__nv_atomic_*,CUTLASS 用到它们)、在主机端调用 CUDA 的 float 版 max 和 min(clang 只把它们声明在设备端),以及带初始化的 __shared__ 变量。

  • 写给其他工具的命令略去了 clice 从中隐藏了文件的目录。 clice command convert 写出的是 clice 编译时所用的命令,但去掉了 GCC 的私有 include 目录和另一个 clang 的内置头文件目录:若保留它们,读取命令的工具会看到其中的所有文件,clang 自己的内置头文件也会经由 #include_next 进入它们的同名版本(另一个 clang 的 stdint.h 会让这条链在到达 C 库的版本之前就终止)。因此,读取转换后命令的工具找不到只有那个编译器才有的头文件(omp.h)。clice command --json 给出完整的命令,并列出每个目录中被隐藏的文件(hidden):需要这些头文件的工具可以重新搜索该目录,再用自己的文件系统覆盖层(overlay)隐藏列出的文件,例如 clang 的 -ivfsoverlay。

  • 不读取头文件映射(header map)。 指向头文件映射的 -I(foo.hmap,由 Xcode 自己的构建写出)会为编译重新映射 include 名称,但不作用于 clice 自己的 include 搜索:依赖关系、#include 补全和文档链接。这一搜索也不会进入伞形 framework(umbrella framework)的子 framework(Carbon.framework/Frameworks/HIToolbox.framework)。

  • 配置规则的全局影响。 clice.toml 中的 [[rules]] 可以向编译命令追加或移除选项。如果用户修改了影响所有文件的规则(例如追加一个全局的 -I),所有文件的编译配置都会改变,可能触发全量重索引。目前没有机制检测哪些规则变更实际影响了哪些文件。

  • MSVC 风格选项解析。 在非 Windows 系统上,必须特别处理 MSVC 风格选项前缀(/U、/D、/I),避免 Unix 绝对路径(如 /Users/...)被误解析为 MSVC 选项。目前通过根据驱动名称动态调整选项可见性来解决,但边界情况仍可能存在。

  • 只识别常见的编译器启动器。 ccache、sccache、distcc 和 icecc 会连同它们自己的选项和环境变量赋值一起从命令中去掉,clice 询问的是它们后面的编译器。其他启动器会被当成编译器,导致家族识别和工具链查询以错误的二进制文件为目标;请从编译数据库的命令中去掉它。