| # 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: |
| |
| * `--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 `--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][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][fidl-style] or [FIDL |
| API Rubric][fidl-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`. |
| |
| ```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 |
| [fidl-rubric]: /docs/development/api/fidl.md |
| [schema]: /tools/fidl/fidlc/schema.json |