“Clang” CFE Internals Manual

    • 介绍
    • LLVM 支持库
    • Clang 基本库
      • 诊断子系统
        • Diagnostic*Kinds.td 文件
        • 格式化串
        • 格式化一个诊断参数
        • 生成诊断信息
        • Fix-It 提示
        • DiagnosticClient 接口
        • 为 Clang 添加翻译
      • SourceLocation 和 SourceManager 类
      • SourceRange 和 CharSourceRange
    • 预编译的头文件
    • 前端库
    • Lexer 和 预处理器库
      • Token 类
      • Annotation 关键字
      • Lexer 类
      • TokenLexer 类
      • MultipleIncludeOpt 类
    • Parser 库
    • AST 库
      • Type 类及其子类
        • Canonical 类型
      • QualType 类
      • 声明名称
      • 声明上下文
        • 重声明(Redeclarations)和重载(Overloads)
        • 词法和语义上下文
        • 透明声明上下文(Transparent Declaration Contexts)
        • 多重定义声明上下文(Multiply-Defined Declarations Contexts)
      • Clang AST 中的常量折叠
        • 实现方法
        • 扩展
    • 如何改变 Clang
      • 如何添加属性
        • 属性基础
        • include/clang/Basic/Attr.td
        • 引用
        • The meat of your attribute
      • 如何添加表达式和 statement

    LLVM libsupport 库提供了许多底层库(underlying libraries) 和 数据结构，包括了命令行选项的处理，各种容器(various containers) 和 一个用于访问文件系统系统抽象层。

    这个库明显需要一个更好的名称。基本库包含了一系列底层实用功能来跟踪和操作 source buffers，source buffer 内部位置，诊断信息，关键字，目标抽象和要编译的语言的子集信息。

    这个架构的一部分是针对 C的（例如 TargetInfo 类），其他部分可以被重用于非基于 C 的语言（SourceLocation, SourceManager, Diagnostics, FileManager）。当将来需要的时候，我们可以看出引进一个新库，把一些 general 类移到其它地方，或者引入其他的解决方案是否有意义。

    我们实用依赖顺序来描述这些类。

    在这一节中，我们将会给出一些有 Clang 命令行驱动产生的例子，但是诊断信息可以根据DiagnosticClient接口的实现而具有不同的渲染方式。一个具有代表新的诊断信息：

    在这个例子中，你可以看到英文翻译，级别(error)，可以看到源位置(^号和文件/行/列信息)，源码范围”~~~~”,诊断参数("int *" 和 "_Complex float")。你需要相信我，这个诊断背后有个唯一的 ID :)。

    让所有这些发生需要几个步骤并牵扯到很多移动，这一节介绍了它们并且讨论了添加一个新的诊断的最佳实践。

    Diagnostic*Kinds.td 文件

    诊断信息的创建通过添加入口到clang/Basic/Diagnostic*Kinds.td文件，取决于什么样的库将会用它。从这个文件，tblgen产生诊断的唯一 ID、级别和从格式化字符串产生英语翻译。

    严重程度来源于集合{NOTE, REMARK, WARNING, EXTENSION, EXTWARN, ERROR}。其中ERROR用于指示无论在何种情况下程序都是无法接受的。当错误发生时，输入程序的AST可能还没有完整生成。EXTENSION和EXTWARN用于Clang 接受的语言扩展。这意味着 Clang 可以完全理解并在 AST 中表示，但是我们还是生成诊断信息告诉用户它们的代码是不可移植的。其中的区别是前者默认被忽略，后者默认会警告。WARNING用于那些在当前源码语言中可以有效构建但是在某些情况下可能存在歧义。REMARK提供了与具体歧义无关的通用信息。NOTE用于给前边的诊断信息添加更多信息。

    这些诊断级别被基于各种配置的诊断子系统映射为一个更小的输出级别集合(就是Diagnostic::Level枚举， {Ignored, Note, Remark, Warning, Error, Fatal})。Clang 内部支持一个完善的分层映射机制可以允许你映射几乎所有的诊断到你想要的输出级别。唯一不可被映射的就是NOTES，它总是紧跟着前边的诊断和ERRORS,其中ERROR只能被映射为(例如不可能把错误变成警告)。

    诊断映射具有多种使用方式。例如，如果用户指定了-pedantic, EXTENSION就被映射为Warning,如果指定了-pedantic-errors, 就被映射为Error。这被用来实现像-Wunused_macros, -Wundef等等选项。

    映射为Fatal只应当在用于在错误严重到错误恢复无法修复的时候(这样会生成大量的伪错误)。这类例子之一就是#include一个文件失败。

    格式字符串(The Format String)

    1. "binary integer literals are an extension"
    2. "format string contains '\\0' within the string body"
    3. "more '%%' conversions than data arguments"
    4. "invalid operands to binary expression (%0 and %1)"
    5. "overloaded '%0' must be a %select{unary|binary|unary     or binary}2 operator"
    6.      " (has %1 parameter%s1)"

    这些例子展示了格式化字符串的某些重要性。你可以使用普通的 ASCII 字符串，除了%，但是这些事 C 字符串，所以你要像上边第二个例子一样使用并且小心 escape sequences。如果你想生成一个%，使用%%escape sequence，像上例中第三个一样。最终，Clang 使用序列来指定诊断参数的位置和如何格式化。