# 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
       │           ├── 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

The exception is [Dart code](#dart), which is generated in the `dartlang`
toolchain. For `fuchsia.io`, the root of the Dart output is
`out/default/dartlang/gen/sdk/fidl/fuchsia.io`. The rest of this document refers
to this as the Dart root directory. It is structured as follows:

    out/default/dartlang/gen/sdk/fidl/fuchsia.io
    └── fuchsia.io_package
       └── lib
          ├── fidl_async.dart
          └── fidl_test.dart

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`, `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/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

#### Dart {#dart}

The Dart bindings are generating in the Dart root directory as
`${target_name}/${library_name}_package`. For example, with `fuchsia.io`:

    out/default/dartlang/gen/sdk/fidl/fuchsia.io/fuchsia.io_package

Within the package, `lib/fidl_async.dart` contains the bindings code.
`lib/fidl_test.dart` contains utilities for [testing][dart-testing].

## Using fidlbolt

For ad hoc examples or existing FIDL files, another option is to use the
`fidlbolt` tool. By pasting the desired FIDL content into fidlbolt, it is
possible to view the output for each binding, as well as for the JSON IR.
`fidlbolt` also supports viewing libraries defined in the SDK, e.g. `library
fuchsia.io;`, as well as importing them, e.g. `using fuchsia.io;`.

## 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
[dart-testing]: /docs/reference/fidl/bindings/dart-bindings.md#test-scaffolding