docs/development/languages/fidl/guides/generated-code.md

# Generated code output guide

This document outlines the approaches available for viewing generated FIDL
bindings code. For general information about how FIDL definitions get converted
to target language code, refer to the [bindings reference][bindings-ref].

The FIDL library `fuchsia.io` is used throughout as a running example. It is
defined in [//sdk/fidl/fuchsia.io](/sdk/fidl/fuchsia.io).

## Viewing generated code

This section shows how to directly access generated code files.

### GN build

If you would like to look at the generated output for a specific target in the
Fuchsia build, you can first build the target in question, then inspect the
generated files in the build output. The instructions in this section assume
that the target is defined using the standard [`fidl` GN template][fidl-gn], and
that the build directory is set to the default path (`out/default`). `fx status`
can be used to find the current build directory.

You can find most FIDL output in the GN build in the `fidling` toolchain. For
`fuchsia.io`, the root of the output is
`out/default/fidling/gen/sdk/fidl/fuchsia.io`. The rest of this document refers
to this as the root directory. It is structured as follows:

    out/default/fidling/gen/sdk/fidl/fuchsia.io
    ├── fuchsia.io.fidl.json
    └── fuchsia.io
       ├── fidl_fuchsia_io.rs
       ├── fuchsia.io.fidl
       │  └── impl.go
       ├── c
       │  └── fuchsia
       │     └── io
       │        └── c
       │           ├── fidl.h
       │           ├── fidl.client.c
       │           └── fidl.server.c
       ├── cpp
       │  └── fidl
       │     └── fuchsia.io
       │        └── cpp
       │           ├── common_types.cc
       │           ├── common_types.h
       │           ├── driver
       │           │  ├── fidl.h
       │           │  ├── natural_messaging.cc
       │           │  ├── natural_messaging.h
       │           │  ├── wire.h
       │           │  ├── wire_messaging.cc
       │           │  └── wire_messaging.h
       │           ├── fidl.h
       │           ├── hlcpp_conversion.h
       │           ├── markers.h
       │           ├── natural_messaging.cc
       │           ├── natural_messaging.h
       │           ├── natural_types.cc
       │           ├── natural_types.h
       |           ├── test_base.h
       │           ├── type_conversions.cc
       │           ├── type_conversions.h
       │           ├── wire.h
       │           ├── wire_messaging.cc
       │           ├── wire_messaging.h
       │           ├── wire_test_base.h
       │           ├── wire_types.cc
       │           └── wire_types.h
       └── hlcpp
          └── fuchsia
             └── io
                └── cpp
                   ├── fidl.h
                   ├── fidl.cc
                   └── fidl_test_base.h

Many generated code paths seem to contain duplicate directory names, such as
`.../fuchsia.io/fuchsia.io/...`. This occurs because FIDL libraries are usually
defined in a directory named after the library, with a target named after the
library. The first `fuchsia.io` comes from the directory, and the second comes
from the GN target name.

#### JSON IR

The JSON IR is generated in the root directory as `${target_name}.fidl.json`.
For example, with `fuchsia.io`:

    out/default/fidling/gen/sdk/fidl/fuchsia.io/fuchsia.io.fidl.json

#### Rust {#rust}

The Rust bindings are generated in the root directory as
`${target_name}/${rust_name}.rs`, where `${rust_name}` is derived from the
library name by replacing dots with underscores. For example, with `fuchsia.io`:

    out/default/fidling/gen/sdk/fidl/fuchsia.io/fuchsia.io/fidl_fuchsia_io.rs

#### Go {#go}

The Go bindings are generated in the root directory as
`${target_name}/${library_name}.fidl/impl.go`. For example, with `fuchsia.io`:

    out/default/fidling/gen/sdk/fidl/fuchsia.io/fuchsia.io/fuchsia.io.fidl/impl.go

#### C++ {#c-family}

New C++ bindings use a source layout in subdirectories of the root
directory follow the pattern: `${target_name}/${binding_flavor}/fuchsia.io/cpp`.

From there C++ outputs `wire_types.h`, `wire_types.cc`, `wire_messaging.h`,
`wire_messaging.cc`, `wire.h` and `wire_test_base.h` for using wire types, and
`natural_types.h`, `natural_types.cc`, `natural_messaging.h`,
`natural_messaging.cc`, `test_base.h`, `fidl.h` for using natural types
alongside wire types.

`common_types.h` and `markers.h` are shared between wire and natural types.

For example, using `fuchsia.io` with the C++ bindings creates the following
files:

    out/default/fidling/gen/sdk/fidl/fuchsia.io/fuchsia.io/cpp/fidl/fuchsia.io/cpp/markers.h
    out/default/fidling/gen/sdk/fidl/fuchsia.io/fuchsia.io/cpp/fidl/fuchsia.io/cpp/common_types.h
    out/default/fidling/gen/sdk/fidl/fuchsia.io/fuchsia.io/cpp/fidl/fuchsia.io/cpp/common_types.cc
    out/default/fidling/gen/sdk/fidl/fuchsia.io/fuchsia.io/cpp/fidl/fuchsia.io/cpp/wire_types.h
    out/default/fidling/gen/sdk/fidl/fuchsia.io/fuchsia.io/cpp/fidl/fuchsia.io/cpp/wire_types.cc
    out/default/fidling/gen/sdk/fidl/fuchsia.io/fuchsia.io/cpp/fidl/fuchsia.io/cpp/wire_messaging.h
    out/default/fidling/gen/sdk/fidl/fuchsia.io/fuchsia.io/cpp/fidl/fuchsia.io/cpp/wire_messaging.cc
    out/default/fidling/gen/sdk/fidl/fuchsia.io/fuchsia.io/cpp/fidl/fuchsia.io/cpp/wire.h
    out/default/fidling/gen/sdk/fidl/fuchsia.io/fuchsia.io/cpp/fidl/fuchsia.io/cpp/wire_test_base.h
    out/default/fidling/gen/sdk/fidl/fuchsia.io/fuchsia.io/cpp/fidl/fuchsia.io/cpp/natural_types.h
    out/default/fidling/gen/sdk/fidl/fuchsia.io/fuchsia.io/cpp/fidl/fuchsia.io/cpp/natural_types.cc
    out/default/fidling/gen/sdk/fidl/fuchsia.io/fuchsia.io/cpp/fidl/fuchsia.io/cpp/natural_messaging.h
    out/default/fidling/gen/sdk/fidl/fuchsia.io/fuchsia.io/cpp/fidl/fuchsia.io/cpp/natural_messaging.cc
    out/default/fidling/gen/sdk/fidl/fuchsia.io/fuchsia.io/cpp/fidl/fuchsia.io/cpp/test_base.h
    out/default/fidling/gen/sdk/fidl/fuchsia.io/fuchsia.io/cpp/fidl/fuchsia.io/cpp/type_conversions.h
    out/default/fidling/gen/sdk/fidl/fuchsia.io/fuchsia.io/cpp/fidl/fuchsia.io/cpp/type_conversions.cc
    out/default/fidling/gen/sdk/fidl/fuchsia.io/fuchsia.io/cpp/fidl/fuchsia.io/cpp/hlcpp_conversion.h
    out/default/fidling/gen/sdk/fidl/fuchsia.io/fuchsia.io/cpp/fidl/fuchsia.io/cpp/fidl.h

As the new C++ bindings take shape more bindings will follow this pattern.
See below for how the not-yet unified bindings are generated.

#### HLCPP, and C {#hlcpp-c}

HLCPP and C bindings are generated in subdirectories of the root directory
following the pattern `${target_name}/${binding_flavor}/fuchsia/io`. From there,

- HLCPP outputs `cpp/fidl.cc`, `cpp/fidl.h`, and `cpp/fidl_test_base.h`.
- C outputs `c/fidl.client.c`, `c/fidl.server.c`, and `fidl.h`.

For example, using `fuchsia.io` with the HLCPP bindings creates the
following files:

    out/default/fidling/gen/sdk/fidl/fuchsia.io/fuchsia.io/hlcpp/fuchsia/io/cpp/fidl.cc
    out/default/fidling/gen/sdk/fidl/fuchsia.io/fuchsia.io/hlcpp/fuchsia/io/cpp/fidl.h
    out/default/fidling/gen/sdk/fidl/fuchsia.io/fuchsia.io/hlcpp/fuchsia/io/cpp/fidl_test_base.h

## Viewing generated documentation

### Rust

Documentation for all Rust crates used in Fuchsia, included Rust bindings of
FIDL libraries, is hosted online at
[fuchsia-docs.firebaseapp.com](https://fuchsia-docs.firebaseapp.com/rust).
You can generate offline documentation with [`fx rustdoc`][rustdoc].

<!-- xrefs -->
[bindings-ref]: /docs/reference/fidl/bindings/overview.md
[fidl-gn]: /build/fidl/fidl.gni
[rustdoc]: /docs/development/languages/rust/fidl_crates.md#documentation