# Copyright 2023 The Chromium 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/group_with_inputs.gni")

# Declares license metadata.
#
# Usage:
# ======
# Use to declare license targets that are referenced in the "applicable_licenses"
# parameter of each target declaration.
#
# Example of usage in a third_party/foo/BUILD.gn:
# ```
#   license("license") {
#     public_package_name = "foo",
#     license_files = ["src/LICENSE"],
#   }
#
#   source_set("libfoo") {
#     applicable_licenses = [":license"],
#     sources = [
#       "src/foo.c",
#       "src/foo.h",
#       ...
#     ]
#     ...
#   }
# ```
#
# Alternatively, `applicable_licenses = [...]` can be set
# at the global scope in which case it will apply to all targets
# in the scope. For example:
# ```
#   license("license") {
#     public_package_name = "foo",
#     license_files = ["src/LICENSE"],
#   }
#
#   applicable_licenses = [":license"]
#
#   source_set("libfoo") {
#     ...
#   }
#
#   source_set("libfoo_helper") {
#     ...
#   }
# ```
#
# Very Important:
# ===============
# When using `applicable_licenses` with a GN template, make sure that the
# template forwards the parameter to all of its internal actions.
# Ditto for any other templates invoked by that template, recursively.
# Do that by adding (or modifying the existing)
# `forward_variables_from(invoker, ["applicable_licenses"])` calls
# (similar to "testonly" forwarding). For example: fxr/953227.
#
# Implementation:
# ===============
# Internally, the target will have a 'license' metadata
# scope with the following schema:
# {
#   target_label: The label of the target.
#   public_package_name: The public package name of the license.
#   license_files: List if source files.
# }
#
# The metadata is collected `generated_licenses_spdx` targets
# (see //build/licenses/generated_licenses_spdx.gni).
#
# Parameters:
#
#   public_package_name (required)
#     The publicly-facing name of the licensed package.
#
#     The name may appear in end-user-facing open source compliance notices, and
#     to populate https://spdx.github.io/spdx-spec/v2.3/package-information/#71-package-name-field.
#
#     The name is typically the name of the 3P package as it appears in
#     open-source contexts, i.e. the name of the 3P project.
#
#     For example: "icu" or "grpc".
#
#   license_files (required)
#     List of license text file paths, must have at least one item.
#
template("license") {
  assert(defined(invoker.public_package_name),
         "Must specify public_package_name.")
  assert(defined(invoker.license_files), "Must specify license_files.")
  assert(invoker.license_files != [], "Must specify one or more license_files.")

  target_label = get_label_info(":${target_name}", "label_with_toolchain")

  _metadata = {
    license = [
      {
        target_label = target_label
        public_package_name = invoker.public_package_name
        license_files = invoker.license_files
      },
    ]
  }

  group_with_inputs(target_name) {
    metadata = _metadata
    sources = invoker.license_files
    public_deps = []
  }
}