FIDL Compiler and Tools

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:

  • --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. 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 --files [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.

  • --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 issues warnings about content that compiles (technically valid FIDL), but appears to violate rules from the FIDL Style Guide or FIDL API Rubric. It enforces stylistic conventions and, when possible, mechanically-detectable rubric guidelines.

Readability is important, and style is a component of that. In addition, following these guides helps ensure cross-language portability for the FIDL API.

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.

fx lint

To review other available options, run:

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:

fx format-code