build/fidl/fidl_summary.gni

# Copyright 2022 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/compiled_action.gni")

# Generates the FIDL API summary files based on the FIDL IR generated
# by fidlc.

_fidl_api_summarize_tool = "//tools/fidl/fidl_api_summarize"

# Generates a human-readable FIDL API summary.
#
# For details on the FIDL API summary format, see RFC-0076 at:
# https://fuchsia.dev/fuchsia-src/contribute/governance/rfcs/0076_fidl_api_summaries
#
# Args:
#
# inputs: list(label)
#   A singleton list naming the FIDL IR file to read.
#
# outputs: list(label)
#   A singleton list naming the output API summary file to generate.
#
# testonly: bool(optional)
#
# deps: list[label]
#
# visiblility: list[label]
template("fidl_summary") {
  compiled_action("${target_name}") {
    forward_variables_from(invoker,
                           [
                             "testonly",
                             "deps",
                             "inputs",
                             "outputs",
                             "visibility",
                           ])

    assert(defined(inputs), "inputs is required")
    assert(inputs != [] && inputs == [ inputs[0] ],
           "inputs must have exactly one element")
    assert(defined(outputs), "outputs is required")
    assert(outputs != [] && outputs == [ outputs[0] ],
           "outputs must have exactly one element")
    tool = _fidl_api_summarize_tool
    args = [
      "--fidl-ir-file",
      rebase_path(inputs[0], root_build_dir),
      "--output-file",
      rebase_path(outputs[0], root_build_dir),
    ]
  }
}

# Generates a machine-readable, JSON-formatted, FIDL API summary.
#
# For details on the FIDL API summary format, see RFC-0076 at:
# https://fuchsia.dev/fuchsia-src/contribute/governance/rfcs/0076_fidl_api_summaries
#
# Generates metadata as follows:
#
# metadata = {
#   plasa = [
#     kind = ... # "api_fidl" if unset, or invoker.kind if set.
#     file = ... # The label of the generated output file.
#     path = ... # The filesystem path of the generated summary file
#     dest = ... # Placement of the generated output file in the manifest.
#   ]
# }
#
# Args:
#
# inputs: list(label)
#   A singleton list naming the FIDL IR file to read.
#
# outputs: list(label)
#   A singleton naming the output API summary file to generate.
#
# dest: "fidl"|"vdso"
#   The destination packaging directory for the code.
#
# testonly: bool(optional)
# deps: list(label)
# visiblility: list(label)
template("fidl_summary_json") {
  compiled_action("${target_name}") {
    forward_variables_from(invoker,
                           [
                             "testonly",
                             "deps",
                             "dest",
                             "inputs",
                             "outputs",
                             "visibility",
                           ])
    assert(defined(dest), "dest is required")
    assert(dest == "fidl" || dest == "vdso",
           "dest must be either 'fidl' or 'vdso'")

    assert(defined(inputs), "inputs is required")
    assert(inputs != [] && inputs == [ inputs[0] ],
           "inputs must have exactly one element")
    _json_representation = inputs[0]

    assert(defined(outputs), "outputs is required")
    assert(defined(outputs) && outputs != [] && outputs == [ outputs[0] ],
           "outputs must have exactly one element")
    _summary_file_json = outputs[0]

    tool = _fidl_api_summarize_tool
    args = [
      "--format",
      "json",
      "--fidl-ir-file",
      rebase_path(_json_representation, root_build_dir),
      "--output-file",
      rebase_path(_summary_file_json, root_build_dir),
      "--suppress-empty-library",
    ]
    metadata = {
      # Refer to //sdk/cts/plasa/plasa_artifacts.gni for the explanation of
      # this metadata item.
      plasa = [
        {
          kind = "api_${dest}"
          file = _summary_file_json
          path = rebase_path(_summary_file_json, root_build_dir)
          dest = "${dest}/" + rebase_path(_summary_file_json, target_gen_dir)
        },
      ]
      if (defined(invoker.metadata)) {
        forward_variables_from(invoker.metadata, "*")
      }
    }
  }
}