build/fidl/fidl.gni

# Copyright 2018 The Fuchsia Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.

import("//build/dart/toolchain.gni")
import("//build/fidl/toolchain.gni")
import("//build/go/toolchain.gni")

# Declares a FIDL library.
#
# It expands to different targets depending on $current_toolchain:
#
#   fidl_toolchain
#     ${target_name}
#       Invokes fidlc to produce JSON IR. Also runs fidl-lint and SDK checks.
#     ${target_name}_${binding_name}_generate
#       (Bindings: rust, hlcpp, llcpp, banjo_{c,cpp,rust}, bindlib)
#       Invokes fidlgen_${binding_name} on IR from ${target_name}($fidl_toolchain).
#   go_toolchain, dart_toolchain
#     ${target_name}
#       Invokes fidlgen_{go,dart} on IR from ${target_name}($fidl_toolchain),
#       and compiles the result as a library.
#   all other toolchains
#     ${target_name}_${binding_name}
#       (Bindings: rust, hlcpp, llcpp, banjo_{c,cpp,rust}, bindlib)
#       Compiles ${target_name}_${binding_name}_generate($fidl_toolchain) as a
#       source_set or rustc_library.
#       TODO(fxbug.dev/102954): Rust is inconsistent and uses ${target_name}-rustc.
#     ${target_name}_tables
#       Compiles the coding tables from ${target_name}($fidl_toolchain).
#     ${target_name}_c
#       Compiles the C simple client/server from ${target_name}($fidl_toolchain).
#
# Running code generators in the FIDL toolchain ensures we only codegen once
# rather than N times for fuchsia/host, x64/arm, ASan, etc.
#
# Users of the bindings should depend on:
#
#   ${target_name}($dart_toolchain) for Dart bindings
#   ${target_name}($go_toolchain) for Go bindings
#   ${target_name}_${binding_name} for all other bindings
#
# Parameters
#
#   sources (required)
#     List of paths to library source files.
#
#   name (optional)
#     Name of the library.
#     Defaults to the target's name.
#
#   sdk_category (optional)
#     Publication level of the library in SDKs.
#     See //build/sdk/sdk_atom.gni.
#
#   api (optional)
#     Path to the file representing the API of this library.
#     This file is used to ensure modifications to the library's API are
#     explicitly acknowledged. It is mandatory for publication categories of
#     "partner" or "public".
#     Defaults to "<target name>.api".
#
#   excluded_checks (optional)
#     A list of fidl-lint check IDs to ignore (by passing the command line flag
#     "-e some-check-id" for each value).
#
#   fuzzers (optional)
#     Protocol/methods for which to generate LibFuzzer fuzz targets. Example:
#       [
#         {
#           # Required:
#           protocol = "fully.qualified.FIDLProtocolName"
#           # Optional. Default: All methods in protocol.
#           methods = [ "MethodName1", "MethodName2", ... ]
#         },
#         ...
#       ]
#
#   golden_fuzzer (optional)
#     Boolean flag to generate a LibFuzzer fuzz target for all protocols, used
#     to ensure fuzzers for golden libraries compile successfully.
#
#   experimental_flags (optional)
#     A list of experimental fidlc features to enable.
#
#   goldens_dir (optional, default "//sdk/history")
#     The directory containing golden files for this FIDL API, per API level.
#     Should not contain a trailing slash. This is only used if the API is
#     publishable in an SDK.
#
#   non_fidl_deps (optional)
#     A list of non-FIDL dependency targets, i.e. targets that don't contribute
#     FIDL artifacts, but should be built before this target regardless. This is
#     typically used when `sources` contains files generated by another target.
#
#   should_lint (optional, boolean)
#     If set to false, the linting step is skipped.
#
#   lenient_api_summary (optional, boolean, default false)
#     If false, the builder will check the generated FIDL API summary files against
#     their checked in version.  If true, the checks will emit warnings instead
#     of errors. This switch is used to deploy API summary checks across petals
#     without breaking global integration.
#
#   dart_analysis (optional, boolean, default false)
#     If set to true, dart analysis is run on generated Dart bindings.
#     Dart analysis can take tens of seconds to finish, so running it for all
#     generated Dart bindings is wasteful. This parameter allows us to only run
#     analysis on goldens, and skip for other generated bindings. See fxb/82975
#     for details.
#
#   contains_drivers (optional, boolean, default false)
#     Indicates if any of the FIDL files contain the driver transport or
#     references to the driver transport.
#
#   public_deps
#   testonly
#   visibility
#
template("fidl") {
  assert(defined(invoker.sources), "A FIDL library requires some sources.")
  assert(!defined(invoker.deps),
         "All FIDL dependencies are inherently " +
             "public, use 'public_deps' instead of 'deps'.")

  # Parameters forwarded to nearly every internal template.
  common_parameters = [
    "name",
    "public_deps",
    "sdk_category",
    "testonly",
    "visibility",
  ]

  # Parameters forwarded only to fidl_library.
  fidl_only_parameters = [
    "api",
    "excluded_checks",
    "experimental_flags",
    "goldens_dir",
    "lenient_api_summary",
    "non_fidl_deps",
    "should_lint",
    "sources",
  ]

  # Parameters forwarded only to fidl_dart.
  dart_only_parameters = [ "dart_analysis" ]

  # Parameters forwarded only to fidl_go.
  go_only_parameters = []

  # Parameters forwarded only to fidl_cpp_family.
  cpp_only_parameters = [
    "contains_drivers",
    "fuzzers",
    "golden_fuzzer",
  ]

  all_parameters =
      common_parameters + fidl_only_parameters + dart_only_parameters +
      go_only_parameters + cpp_only_parameters

  # Allow generated targets visibility to their dependant generated targets
  if (defined(invoker.visibility)) {
    invoker.visibility += [ ":*" ]
  }

  if (current_toolchain == fidl_toolchain) {
    needed_parameters =
        common_parameters + fidl_only_parameters + cpp_only_parameters
    not_needed(invoker, all_parameters - needed_parameters)

    # FIDL toolchain: run fidlc to generate the JSON IR.
    import("//build/fidl/fidl_library.gni")
    fidl_library(target_name) {
      forward_variables_from(invoker, common_parameters + fidl_only_parameters)
    }

    # The targets below generate bindings from the JSON IR, but they do not
    # build them. That is done in the target toolchain (when current_toolchain
    # is anything other than {fidl,go,dart}_toolchain).

    import("//build/cpp/fidl_cpp.gni")
    fidl_cpp_family(target_name) {
      forward_variables_from(invoker, common_parameters + cpp_only_parameters)
    }

    import("//build/banjo/fidl_banjo.gni")
    fidl_banjo(target_name) {
      forward_variables_from(invoker, common_parameters)
    }

    import("//build/rust/fidl_rust.gni")
    fidl_rust(target_name) {
      forward_variables_from(invoker, common_parameters)
    }

    import("//build/bind/fidl_bind_library.gni")
    fidl_bind_library(target_name) {
      forward_variables_from(invoker, common_parameters)
    }
  } else if (current_toolchain == dart_toolchain) {
    # Dart toolchain: generate Dart bindings and build/analyze them.
    import("//build/dart/fidl_dart.gni")
    dart_parameters = common_parameters + dart_only_parameters
    not_needed(invoker, all_parameters - dart_parameters)
    fidl_dart(target_name) {
      forward_variables_from(invoker, dart_parameters)
    }
  } else if (current_toolchain == go_toolchain) {
    # Go toolchain: generate Go bindings and build them.
    import("//build/go/fidl_go.gni")
    go_parameters = common_parameters + go_only_parameters
    not_needed(invoker, all_parameters - go_parameters)
    fidl_go(target_name) {
      forward_variables_from(invoker, go_parameters)
    }
  } else {
    needed_parameters = common_parameters + cpp_only_parameters
    not_needed(invoker, all_parameters - needed_parameters)

    # The targets below build code that was generated in the FIDL toolchain.

    import("//build/cpp/fidl_cpp.gni")
    fidl_cpp_family(target_name) {
      forward_variables_from(invoker, common_parameters + cpp_only_parameters)
    }

    import("//build/banjo/fidl_banjo.gni")
    fidl_banjo(target_name) {
      forward_variables_from(invoker, common_parameters)
    }

    import("//build/rust/fidl_rust.gni")
    fidl_rust(target_name) {
      forward_variables_from(invoker, common_parameters)
    }

    import("//build/bind/fidl_bind_library.gni")
    fidl_bind_library(target_name) {
      forward_variables_from(invoker, common_parameters)
    }

    import("//build/c/fidl_c.gni")
    fidl_tables(target_name) {
      forward_variables_from(invoker, common_parameters)
    }

    # The C client/server are only provided on Fuchsia, not host.
    if (is_fuchsia) {
      fidl_c(target_name) {
        forward_variables_from(invoker, common_parameters)
      }
    }
  }
}