# FIDL Compiler and Tools

## Compiler Interface {#compiler-interface}

### Overview

The FIDL compiler is split into a frontend and a number of backends. The compiler processes one
library at a time. The frontend consumes the FIDL declarations for the library (as well as for all
transitive dependencies), performs semantic analysis, and outputs an intermediate representation of
the library. The backends consume the intermediate representation and generate language-specific
bindings for the library.

### Frontend

The frontend is a command-line program named `fidlc`. The `fidlc` compiler has these flags:

* `--c-header HEADER_PATH`. If present, this flag instructs `fidlc` to output a C header at the
  given path. The C header generation could have been implemented as a C backend, but for practical
  reasons, the C header generation is integrated directly into the frontend.

* `--tables TABLES_PATH`. If present, this flag instructs `fidlc` to output coding tables at the
  given path. The coding tables are required to encode and decode messages from the C and C++
  bindings.

* `--json JSON_PATH`. If present, this flag instructs `fidlc` to output the library's intermediate
  representation at the given path. The intermediate representation is JSON that conforms to [a
  particular schema][schema]. The intermediate representation is used as
  input to the various backends.

* `--name LIBRARY_NAME`. If present, this flag instructs `fidlc` to validate that the library
  being compiled has the given name. This flag is useful to cross-check between the library's
  declaration in a build system and the actual contents of the library.

* `--files [FIDL_FILE...]...`. Each `--file [FIDL_FILE...]` chunk of arguments describes a
  library, all of which must share the same top-level library name declaration. Libraries must be
  presented in dependency order, with later libraries able to use declarations from preceding
  libraries but not vice versa. Output is only generated for the final library, not for each of
  its dependencies.

All of the flags can also be provided through a response file, denoted as `@responsefile`. The
contents of the file at `responsefile` will be interpreted as a whitespace-delimited list of
arguments. Response files cannot be nested, and must be the only argument.

### Backend

The backend is a command-line program named `fidlgen`. The `fidlgen` compiler has these flags:

* `--json`. Required. The path to the intermediate representation of the library. The
  intermediate representation is JSON that conforms to [a particular
  schema][schema].

* `--generators`. Required. A comma-separated list of generators to run on the given library. The
  following generators are supported: `cpp`, `go`, `dart`, and `rust`.

* `--output-base`. Required. The base file name for files generated by this generator. The
  generator creates files by adding extensions to this file name. For example, the `cpp`
  backend generates two files, one with the `.h` extension and another with the `.cc` extension.

* `--include-base`. Required. The base directory relative to which C and C++ `#include`
  directives should be computed. For example, when the `cpp` backend generates an `#include`
  directive to reference the `.h` file from the `.cc` file, the backend creates the `#include`
  path relative to this directory.

### Limitations

For the `cpp` backend, the generated `.h` file must be includable as `#include
<fuchsia/cpp/$LIBRARY_NAME.h>`, where `$LIBRARY_NAME` is the name of the corresponding FIDL
library. Typically, that means that the `--output-base` flag will have the value
`$INCLUDE_BASE/fuchsia/cpp/$LIBRARY_NAME`, where `$INCLUDE_BASE` is the value of the
`--include-base` flag.

## Linter

The FIDL linter is a command line program that processes one or more FIDL
files, and prints warnings about content that compiles (technically valid FIDL),
but appears to violate rules from the [FIDL Style Rubric][fidl-style].
Readability is important, and style is a component of that, but the FIDL Rubric
also defines rules that help ensure the FIDL API does not include things that are
known to hamper cross-language portability.

### Use `fx lint`

Fuchsia includes the `fx lint` command that automatically selects and runs the
appropriate code linter for each of a set of specified files. `fx lint` bundles
the files with a `.fidl` extension, and passes all of them, together, to the FIDL
linter command `fidl-lint`.

`fx lint` is the recommended way to invoke the FIDL linter, and ideally should be
run before uploading new FIDL libraries or changes to existing FIDL. Without any
arguments, `fx lint` will run all available linters on all files in your most
recent `git commit`.

```sh
fx lint
```

To review other available options, run:

```sh
fx lint --help
```

## Formatter

The FIDL formatter is a command line program that will format .fidl files. It is
automatically built in to the `fx format-code` command, which will format any
modified FIDL files:

```sh
fx format-code
```

<!-- xrefs -->
[fidl-style]: /docs/development/languages/fidl/guides/style.md
[schema]: /zircon/tools/fidl/schema.json