README.md
1# FIDL compiler
2
3## Pipeline
4
5### Loading a file
6
7All the FIDL files in a library compilation are loaded by a
8[SourceManager](include/fidl/source_manager.h). This thing's job is to own the
9buffers backing files. These buffers are kept alive for the entire pipeline.
10Tokens, for example, are essentially a string view plus some metadata describing
11their source location (a file and position).
12
13### Parsing a file
14
15The FIDL compiler first parses each file into an in-memory AST, which is defined
16by the structures in [ast.h](include/fidl/ast.h). This parsing operation starts
17by reading the file into memory, and then lexing the contents into a
18[token](include/fidl/token.h) stream. The [parser](lib/parser.cpp) proper then
19parses the stream into the hierarchical AST. At this point names of types are
20unresolved (they could end up pointing to types in another file or library, or
21simply be garbage), and nested declarations are still nested in the AST.
22
23This step will fail if any of the given files is not valid FIDL.
24
25### Flattening a library
26
27Once all the files are parsed into AST nodes, it's time to flatten the
28representation.
29
30Recall that some declarations can be nested. For instance, a const declaration
31can be present in an interface or struct declaration.
32
33Flattening pulls all the declarations out to one level, which entails computing
34fully qualified names for nested types.
35
36### Resolving names in a library
37
38Many parts of a FIDL file refer to each other by name. For instance, a struct
39may have a field whose type is given by the (possibly qualified) name of some
40other struct. Any name that can't be resolved (because it is not present in any
41of the given files or library dependencies) causes compilation to fail at this
42stage.
43
44### Computing layout
45
46At this stage layouts of all data structures are computed. This includes both
47the coding tables for all of the messages defined by the library, as well as the
48wire formats of those messages. The in-memory representation of this layout is
49defined by the structures in [coded_ast.h](include/fidl/coded_ast.h).
50
51This step can fail in a few ways. If a given message statically exceeds the
52limits of a channel message, compilation will fail. Statically exceeding the
53recursion limit of FIDL decoding will also cause compilation to fail.
54
55### Backend generation
56
57At this stage, nothing about the FIDL library per se should cause compilation to
58fail (anything particular to a certain language binding could fail, or the
59compiler could be given a bogus location to put its output etc.).
60
61#### C Bindings
62
63C bindings are directly generated from the FIDL compiler.
64
65#### Everything except C (C++, Rust, Dart, Go, etc)
66
67The FIDL compiler emits a [JSON intermediate representation (IR)](schema.json).
68The JSON IR is consumed by an out-of-tree program, named the **back-end**, that
69generates the language bindings from the JSON IR.
70
71The officially supported FIDL language back-ends are:
72
73* C++, Rust, and Go:
74 [fidlgen](https://fuchsia.googlesource.com/garnet/+/master/go/src/fidl/compiler/backend)
75* Dart:
76 [fidlgen_dart](https://fuchsia.googlesource.com/topaz/+/master/bin/fidlgen_dart)
77