此页面由 Cloud Translation API 翻译。

Fidl 编译器前端

本文档简要介绍了 FIDL 编译器 fidlc 的内部工作原理。 fidlc 是一个命令行工具，可接受许多 FIDL 文件，然后输出 FIDL JSON IR。

概览

编译器的主要输入是 --files 标志的参数，用于描述按库分组的文件编译器会分别解析每个文件，以获取每个文件：

每个文件都会加载到 SourceFile 中，后者拥有为文件提供支持的缓冲区
编译器会初始化 Lexer，后者将 SourceFile 作为参数构造函数。此类公开了 Lex() 方法，该方法会返回下一个 Token ；可以重复调用该函数以获取文件中 Token 的序列。
编译器会使用 Lexer 初始化 Parser，然后调用 Parse() 方法构建解析树。代码将解析树视为原始 AST。此函数会返回一个 raw::File，此类是表示原始 AST 的根节点的类。
在编译器将每个文件解析为解析树之后，会将解析树分组为每个库都对应一个 AST（在代码中称为扁平 AST）。这个扁平 AST 的根部是 flat::Library。
- 对于每个库，编译器会遍历每个库对应的 raw::File 解析树库，将 raw:: 个节点转换为其对应的 flat:: 个节点。例如， raw::StructDeclaration 会变成 flat::Struct，而 raw::Constant 会变成 flat::Constant。然后，转换后的 flat:: AST 节点会存储在单个 flat::Library。最初，这些扁平 AST 节点包含的信息与原始 AST 相同但它们还包含一些字段，例如 value 字段（用于值）和 typeshape 字段。
在 AST 完全初始化后，编译器会评估常量，并确定所声明类型的内存对齐和大小信息。

。

最后，我们最终得到一个经过处理的扁平 AST，并已准备好进行后端生成绑定或 JSON IR。

列克星

Lexer 主要用于跟踪指向文件数据的两个 char * 指针。通过 current_ 指针用于标记该类的当前位置。token_start_指针标记当前正在使用的词元的开头。每次调用 Lex() 方法时，使 current_ 指针不断移动，直到遍历了完整的词元。然后，Token 会使用两个指针之间的数据构造的。

此示例展示了在短 FIDL 代码段中调用 Lex() 期间指针如何变化 const bool flag = true;：

对 const 关键字进行词法运算后的初始状态：

 const bool flag = true;
      ^current_
      ^token_start_

在下一个词元之前会跳过空格：

const bool flag = true;
      ^current_
      ^token_start_

current_ 指针会一直更新，直到词素结束：

const bool flag = true;
          ^current_
      ^token_start_

此时，返回的下一个 Token 可以开始构建了。通过 location_ 设置为介于 token_start_ 和 current_ 之间的数据。类型设置为 Identifier。在返回之前，指针会被重置，并最终处于与初始状态类似的状态状态。然后，可以对下一个令牌重复此过程：

 const bool flag = true;
           ^current_
           ^token_start_

在内部，可通过以下主要方法操纵这两个指针：

Skip()。通过如下标记跳过任何不必要的字符（例如空格）同时将 current_ 和 token_start_ 指针向前移动。
Consume()。返回当前字符并前进 current_。
Reset()。返回 token_start_ 到 current_ 之间的数据。然后，设置 token_start_ 设置为 current_ 的值。

解析

Parser 的目标是将 Token 流转换为解析树 (raw:: AST)，并采用 Parse() 方法。对 FIDL 文件重复调用 Lex 即可生成 Token 流。这个解析器以递归方式实现下降。原始 AST 的每个节点都有一个相应的 ParseFoo() 方法，该方法使用 Lexer 中的 Token 并返回 unique_ptr 附加到该节点的实例。如果出现失败情况，系统会返回 nullptr。

Parser 会跟踪以下信息：

使用 SourceElements 堆栈构建的当前节点，存储在 active_ast_scopes_ 中。
正在处理的当前和之前的 Token。last_token_和previous_token_：。
Parser::Lex 方法中自己的状态机。当前令牌 (last_token_) 为始终是下一个将使用的词元，这样实际上为解析器提供了一个词元先行（即 LL(1)）。

Parser 根据 Token::Kind 确定当前 Token 属于哪种节点类型 last_token_ 调用 Peek() 方法。然后，Parser 会更新其状态并构造通过使用 ASTScope 类以及 ConsumeToken 和 MaybeConsumeToken 来设置节点辅助方法。

此示例逐行展示了一个简单的非递归 case。解析器方法如下所示：

std::unique_ptr<raw::StringLiteral> Parser::ParseStringLiteral() {
    ASTScope scope(this);
    ConsumeToken(OfKind(Token::Kind::kStringLiteral));
    if (!Ok())
        return Fail();

    return std::make_unique<raw::StringLiteral>(scope.GetSourceElement());
}

它会消耗一个令牌并返回叶节点 raw::StringLiteral：

class StringLiteral : public SourceElement {
public:
    explicit StringLiteral(SourceElement const& element) : SourceElement(element) {}

    virtual ~StringLiteral() {}
}

该方法首先会创建一个新的 ASTScope，它会初始化 SourceElement 稍后通过将其推送到 active_ast_scopes_ 来创建返回的节点。起点 SourceElement 会设置为使用的第一个令牌，并在调用中设置结束然后返回GetSourceElement()。

StringLiteral 的新 SourceElement 会在 ASTScope 构造函数内初始化：

parser_->active_ast_scopes_.push_back(raw::SourceElement(Token(), Token()));

然后，系统会调用 ConsumeToken 来处理下一个令牌。此方法采用构造的谓词与 OfKind() 以及对 last_token_ 的种类或子种类进行谓词的调用。OfKind() 会返回函数，该函数检查其输入是否与给定种类或子种类匹配。如果谓词失败（在在这种情况下，如果当前词法单元不是字符串字面量，则错误会存储在类中，方法返回的值。Ok() 调用会捕获错误，并通过解析错误停止编译器。如果谓词成功，系统将返回堆栈中符合以下条件的任何 SourceElement 的开始令牌：设置为当前令牌：

for (auto& scope : active_ast_scopes_) {
    if (scope.start_.kind() == Token::Kind::kNotAToken) {
        scope.start_ = token;
    }
}

在此示例中，起始标记被设为堆栈的顶层元素，因为它是在方法的开头。然后，Parser 通过设置 previous_token_ = last_token_ 和 last_token_ = Lex() 进入下一个词元。

最后，使用 scope.GetSourceElement() 返回生成的 StringLiteral 节点。这会将将堆栈顶部的 SourceElement 的结束标记传递给 previous_token_，然后会返回 SourceElement。最后一个节点具有相同的开始标记和结束标记， StringLiteral 只有一个令牌，但其他方法可能会消耗多个令牌然后再调用 GetSourceElement()。当该方法返回时，ASTScope 的析构函数会弹出位于 active_ast_scopes_ 范围内的顶部元素。

编译

此时，编译器已为每个输入文件成功构建了一个 raw::File，并且继续分三个步骤将这些原始 AST 编译为扁平的 AST：

用量：原始 AST（其表示法尝试与 FIDL 语法匹配）为按 FIDL 库分组并脱糖为扁平的 AST（其表示法尝试匹配 FIDL 语言语义）。此步骤会将每个文件的一个 raw::File 转换为一个 flat::Library 每个库
拓扑排序：确定平展 AST 节点的解析顺序（请参阅下文步骤）。
Resolution：用于执行名称解析、类型解析以及类型形状和大小计算。解析过程是逐个节点完成的，所得信息存储在 flat:: 节点本身中。

。

观看

每个文件解析为 raw::File 且已得到空的 AST (flat::Library) 后初始化后，需要使用 raw::File 中的所有数据来更新 AST 与之对应的实体。这通过 ConsumeFoo() 方法以递归方式完成。每个 ConsumeFoo() 方法通常将相应的原始 AST 节点作为输入，更新 Library 类，然后返回 bool 以指示成功或失败。这些方法包括负责：

验证属性的位置；例如，检查 Transport 属性是否为只为协议指定
检查是否存在任何未定义的库依赖项（例如，如果使用 textures.Foo， textures 库未导入）
将原始 AST 节点转换为对应的扁平 AST 节点等效节点，并将其存储在 Library 的 foo_declarations_ 属性。最初，扁平 AST 节点的值处于未设置状态但它们会在以后编译期间进行计算。
通过将每个声明添加到 declarations_ 矢量来注册它们。常量声明和枚举/位字段（用于声明值）也会添加到 constants_ 向量，而其他所有声明（声明某个类型）则会获得相应的类型模板添加到库的类型空间中。

拓扑排序

将给定 Library 的所有声明都添加到 declarations_ 向量后，编译器可以继续解析每个单独的声明。不过，它必须在顺序正确（以便先解析声明的所有依赖关系）；这是先将声明排序为单独的 declarations_order_ 向量，然后然后对其进行迭代，以编译每个声明。排序操作是在 SortDeclarations() 方法，并使用 DeclDependencies() 确定依赖项。

分辨率

有了经过排序的声明后，编译过程便通过 CompileFoo 方法进行，通常对应于 AST 节点（例如 CompileStruct、CompileConst），其中 CompileDecl 作为入口点。CompileDecl 的主要用途如下：

TypeDecl 来确定其 TypeShape
Const：解析其值，以及
TypeConstructor 设置其 Type。

完成此步骤后，flat::Library 会包含任何代码的所有必要信息。FIDL 编译器可以直接生成 C 绑定，也可以生成可由单独的后端使用

其他检查

在将编译标记为成功之前，FIDL 编译器还会进行一些额外的检查：例如，它将检查是否满足属性的所有限制，以及是否所有声明的库依赖项

后端生成

FIDL 编译器会发出 JSON 中间表示法 (IR)。JSON IR 由一个名为“back-end”的单独程序使用，该程序可通过该程序生成语言绑定， JSON IR。

官方支持的 FIDL 语言后端包括：

C++： <ph type="x-smartling-placeholder">
- 高级别：fidlgen_hlcpp
- 低级别：fidlgen_cpp
- 统一：fidlgen_cpp
Go：fidlgen_go
Rust：fidlgen_rust

C 绑定

由于历史原因，C 绑定直接由 FIDL 编译器生成，即 C 绑定不支持所有与 C 绑定一起使用的功能和类型都需要使用 Layout = "Simple" 属性。

C 系列运行时

fidlc 还负责生成“编码表”，这是使用的 fidl_type_t 实例用于表示运行时的 FIDL 消息，并由 C 系列的 C 系列的所有绑定使用，（C、LLCPP、HLCPP）。为此，系统会将平面 AST 转换为称为“编码”的将 AST 与 CodedTypesGenerator 搭配使用，后者会遍历给定 flat::Library 中的 flat::Decl，并将每个 raw::Decl 节点转换为相应的 coded::Type 节点（例如 flat::Struct 变为 coded::StructType）。

然后，TablesGenerator 会生成编码表，并为每个代码生成 C 代码用于构造等效 fidl_type_t 类型的 coded::Type。例如，对于 coded::StructType 调用了 MyStruct，TablesGenerator 会写出用于构造等效的 fidl::FidlCodedStruct，如下所示：

const fidl_type_t MyStruct = fidl_type_t(::fidl::FidlCodedStruct(
    my_struct_fields, 1u, 32u, "mylibrary/MyStruct"));

//sdk/fidl 中 FIDL 库的编码表会生成到 out 目录内的 fidling/gen/sdk/fidl/LIBRARY/LIBRARY.fidl.tables.c。例如 out/default/fidling/gen/sdk/fuchsia.sys/fuchsia.sys.fidl.tables.c。README 提供了额外的背景信息。可以找到 fidl_type_t 定义（例如 FidlCodedStruct 的定义）在 internal.h 中。

术语库

声明

Decl 是所有扁平 AST 节点的基础，就像 SourceElement 是所有解析器的基础一样树节点，并且对应于用户在 FIDL 文件中可能做出的所有可能的声明。那里 Decl 有两种类型：

Const，声明一个值，并具有在运行期间解析的 value 属性编译和
TypeDecl，用于声明消息类型或接口，并具有 typeshape 属性会在编译期间设置

表示聚合类型（例如结构体、表和联合）的 TypeDecl 具有静态 Shape() 方法，其中包含用于确定 Typeshape 的逻辑该给定类型。

FieldShape

FieldShape 描述了聚合类型（例如结构体或联合体。通常，这些字段需要 Typeshape 和 FieldShape

名称

Name 表示作用域变量名称，包含该名称所属的库（或者将变量名称指定为 nullptr，而将变量名称指定为字符串（对于匿名名称）或 SourceLocation。在引用 Name 时，您还可以选择性地包含 member_name_ 字段。字段（例如 MyEnum.MyField）。

SourceElement

SourceElement 表示 fidl 文件中的代码块，由 start_ 参数化和end_ Token。所有解析器树（“原始”AST）节点均从此类继承。

SourceFile

文件封装容器，负责拥有该文件中的数据。另请参阅虚拟 SourceFile

SourceLocation

StringView 及其来源的 SourceFile 的封装容器。它提供了一些方法来获取 StringView 周围的行及其位置，以 "[filename]:[line]:[col]" 字符串

SourceManager

封装与单个 Library 相关的一组 SourceFile 的封装容器。

令牌

令牌本质上是一个词素（以 SourceLocation 的形式存储为 location_ 属性），增强了对解析器有用的其他两条信息在编译的后续阶段中会发生以下情况：

种类和子种类，共同对词素进行分类。可能的类型包括： <ph type="x-smartling-placeholder">
- 特殊字符，如 Kind::LeftParen、Kind::Dot、Kind::Comma 等...
- 字符串和数字常量
- 标识符。关键字词元（例如 const、struct）被视为标识符，还定义了一个子种类，以标识它是哪个关键字（例如 Subkind::Const， Subkind::Struct）。所有其他令牌的子种类为 None。
- 未初始化令牌的种类为 kNotAToken。

类型

表示某个类型实例的结构体。例如，vector<int32>:10? 类型对应于一个 VectorType TypeDecl 的实例，其中 max_size_ = 10 和 maybe_arg_type 设置为 Type 与 int32。内置类型都有一个静态 Shape() 方法，在给定参数的情况下，返回该类型的实例的 Typeshape。用户定义的类型（例如结构体或联合体）的类型为 IdentifierType，也就是 TypeDecl（如 Struct）改为提供静态 Shape() 方法。

TypeDecl

请参阅 Decl。

TypeShape

有关如何在内存中布置某个类型的对象（包括其大小）的信息，对齐、深度等

类型空间

类型空间是从 Type 名称到相应 Type 的 TypeTemplate 的映射。中编译时，系统会初始化类型空间以包含所有内置类型（例如 "vector" 映射到 VectorTypeTemplate），而用户定义的类型是在编译过程中添加的。这还可以确保每种类型只存在一个类型模板实例，并避免命名类型的冲突/阴影（例如 https://fxbug.dev/42156366）。

TypeTemplate

TypeTemplates 的实例提供了 Create() 方法，可用于创建特定 Type - 因此每个内置 FIDL 类型（例如 ArrayTypeTemplate、PrimitiveTypeTemplate 等）以及单个类（适用于所有用户定义的一个类型 (TypeDeclTypeTemplate)，一个针对类型别名 (TypeAliasTypeTemplate)。Create() 将可能的类型形参（实参类型、可为 null 性和大小）作为形参。

例如，如需创建一个表示 vector<int32>:10? 类型的对象，编译器会调用参数类型为 int32 的 VectorTypeTemplate 的 Create() 方法，大小上限为 10，以及 types::Nullability::kNullable 是否可为 null。此调用会返回 VectorType 替换为这些参数。请注意，这些参数并非全都适用于所有类型（例如 PrimitiveType，如 int32）都没有这 3 种类型。类型的 Create() 方法模板会自动检查是否只传递了相关的参数。

用户定义的类型的具体类型是 IdentifierType，它由 TypeDeclTypeTemplate。

虚拟源文件

具有虚构“filename”的 SourceFile 子类并且在没有后备数据的情况下初始化。它公开 AddLine() 方法以将数据添加到文件，并用作SourceFile 不直接出现在任何输入 SourceFile 中的内容，例如匿名 Name。