1# FIDL: Compiler Interface 2 3This document describes the command-line interface to the FIDL compiler. 4 5Information on the internals of that tool lives 6[alongside the source of the tool](../../system/host/fidl/README.md). 7 8See [FIDL: Overview](index.md) for more information about FIDL's overall 9purpose, goals, and requirements, as well as links to related documents. 10 11## Overview 12 13The FIDL compiler is split into a frontend and a number of backends. The 14compiler processes one library at a time. The frontend consumes the FIDL 15declarations for the library (as well as for all transitive dependencies), 16performs semantic analysis, and outputs an intermediate representation of the 17library. The backends consume the intermediate representation and generate 18language-specific bindings for the library. 19 20## Frontend 21 22The frontend is a command-line program named `fidlc`. The `fidlc` compiler takes 23a number of arguments: 24 25 * `--c-header HEADER_PATH`. If present, this flag instructs `fidlc` to output 26 a C header at the given path. In principle, the C header generation could 27 have been implemented as a C backend, but for some practical reasons, we 28 integrated the C header generation directly into the frontend. 29 30 * `--tables TABLES_PATH`. If present, this flag instructs `fidlc` to output 31 coding tables at the given path. The coding tables are required to encode and 32 decode messages from the C and C++ bindings. 33 34 * `--json JSON_PATH`. If present, this flag instructs `fidlc` to output the 35 library's intermediate representation at the given path. The intermediate 36 representation is JSON that conforms to [a particular schema](../../system/host/fidl/schema.json). 37 The intermediate representation is used as input to the various backends. 38 39 * `--name LIBRARY_NAME`. If present, this flag instructs `fidlc` to validate 40 that the library being compiled has the given name. This flag is useful to 41 cross-check between the library's declaration in a build system and the 42 actual contents of the library. 43 44 * `--files [FIDL_FILE...]...`. Each `--file [FIDL_FILE...]` chunk of arguments 45 describes a library, all of which must share the same top-level library name 46 declaration. Libraries must be presented in dependency order, with later 47 libraries able to use declarations from preceding libraries but not vice versa. 48 Output is only generated for the final library, not for each of its dependencies. 49 50All of the arguments can also be provided via a response file, denoted as 51`@responsefile`. The contents of the file at `responsefile` will be interpreted 52as a whitespace-delimited list of arguments. Response files cannot be nested, 53and must be the only argument. 54 55## Backend 56 57The backend is a command-line program named `fidlgen`. The `fidlgen` compiler 58takes a number of arguments: 59 60 * `--json` (required). The path to the intermediate representation of the 61 library. The intermediate representation is JSON that conforms to 62 [a particular schema](../../system/host/fidl/schema.json). 63 64 * `--generators` (required). A comma-separated list of generators to run on the 65 given library. The following generators are currently supported: `cpp`, `go`, 66 `dart`, and `rust`. 67 68 * `--output-base` (required). The base file name for files generated by this 69 generator. The generator will create files by adding extensions to this file 70 name. For example, the `cpp` backend generates two files, one with the `.h` 71 extension and another with the `.cc` extension. 72 73 * `--include-base` (required). The base directory relative to which C and C++ 74 `#include` directives should be computed. For example, when the `cpp` backend 75 generates an `#include` directive to reference the `.h` file from the `.cc` 76 file, the backend will create the `#include` path relative to this directory. 77 78## Limitations 79 80For the `cpp` backend, the generated `.h` file must be incluable as 81`#include <fuchsia/cpp/$LIBRARY_NAME.h>`, where `$LIBRARY_NAME` is the name of 82the corresponding FIDL library. Typically, that means that the `--output-base` 83flag will have the value `$INCLUDE_BASE/fuchsia/cpp/$LIBRARY_NAME`, where 84`$INCLUDE_BASE` is the value of the `--include-base` flag. 85