# Copyright 2019 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.

# Write a JSON file for the $target_name "build API module".  The file goes
# at `$root_build_dir/$target_name.json`.  The contents are in JSON format.
#
# The $target_name is the name of the build API module.  It's up to each
# module to define the JSON schema that constitutes the API contract with
# users of this build API module.  Usually somewhere in the JSON structure
# will be strings naming Ninja targets (i.e. output files to produce, or
# actions to take for side-effect such as running tests).
#
# Every build_api_module() should be preceded by a documentation comment
# describing the schema and meaning of the JSON it produces.
#
# Note, this is evaluated only in $default_toolchain context (so that only
# one file is ever generated by each target.  Hence, to define a build API
# module, this target must be reached in the dependency graph from the
# $default_toolchain.  Usually the module needs to express information
# collected from other toolchains.  That is done by having the $deps here
# (eventually) reach targets in other toolchains in the metadata walk.
#
# The //:api build_api_module() target is the root of the whole build API.
# Each other build_api_module() must be reached from its $deps.
#
# Parameters
#
#   contents
#     Optional: Fixed contents of the file, any GN type, serialized as JSON.
#     This must be present if $data_keys et al are not.
#     Type: any
#
#   deps, data_keys, walk_keys
#     Specifies a metadata query to produce the contents of the file.
#     In this case, the file always contains a JSON list.  If $contents
#     is omitted then $data_keys is required.
#     Type: See generated_file().
#
template("build_api_module") {
  if (current_toolchain == default_toolchain) {
    generated_file(target_name) {
      outputs = [
        "$root_build_dir/$target_name.json",
      ]
      forward_variables_from(invoker,
                             [
                               "contents",
                               "deps",
                               "data_keys",
                               "walk_keys",
                               "testonly",
                             ])
      output_conversion = "json"
      metadata = {
        build_api_modules = [ target_name ]
      }
    }
  } else {
    not_needed([ "target_name" ])
    not_needed(invoker, "*")
  }
}