# Copyright 2020 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("fuchsia_component.gni")
import("fuchsia_package.gni")

# Defines a package that contains a single component.
# See: https://fuchsia.dev/fuchsia-src/development/components/build
#
# Developers often define a package that contains a single component.
# This template fuses together fuchsia_package() and fuchsia_component() as a
# convenience.
#
# Packages are units of distribution. It is beneficial to define multiple
# components in the same package if you need to guarantee that several
# components are always co-present, or if you'd like to be able to update
# several components at once (by updating a single package).
# This pattern is also commonly used to create hermetic integration tests.
# For instance an integration test between two components where one is a client
# of a service implemented in another component would include both the client
# and server components.
# However for the sake of simplicity, if you're developing a package with just
# a single component then this template will save you some boilerplate.
#
# Example:
# ```
# executable("rot13_encoder_decoder") {
#   sources = [ "rot13_encoder_decoder.cc" ]
# }
#
# fuchsia_package_with_single_component("rot13") {
#   manifest = "meta/rot13.cml"
#   deps = [ ":rot13_encoder_decoder" ]
# }
# ```
#
# Parameters
#
#   package_name (optional)
#     The name of the package.
#     Type: string
#     Default: target_name
#
#   component_name (optional)
#     The name of the component.
#     Type: string
#     Default: package_name
#
#   manifest (must specify either manifest or cm_label)
#     The component manifest.
#     Type: path
#
#   cm_label (must specify either manifest or cm_label)
#     Use label of a fuchsia_component_manifest target instead of supplying the manifest source.
#     Type: string, GN label e.g. `:my-manifest`
#
#   restricted_features (optional)
#     The set of restricted CML features to allow.
#     The set of features is allowlisted here: //tools/cmc/build/restricted_features/BUILD.gn
#     where each feature name is represented by a group of the same name.
#     Type: list of strings
#     Default: []
#
#   check_includes (optional)
#     Check against expect_includes() in deps.
#     Warning: Do not disable this unless there is a good, documented reason.
#     Type: boolean
#     Default: true
#
#   check_references (optional)
#     Check component manifest references (e.g. "program.binary") against
#     package manifest.
#     Type: boolean
#     Default: true
#
#   experimental_force_runner (optional)
#     Set the --experimental-force-runner flag to the given value.
#     This flag is experimental and may be removed without warning.
#     Type: string
#
#   manifest_deps (optional)
#     Dependencies for the component's manifest, in case it is generated by another target.
#     Type: list of targets
#
#   disable_elf_binaries_checks (optional)
#     Set to true to disable ELF binaries verification checks. Useful
#     if your package includes non-Fuchsia ELF binaries, or if some
#     of them are unstripped.
#     Type: boolean
#     Default: false
#
#   validate_structured_config (optional)
#     If true, check that component manifests which declare config schemas have been
#     packaged with the resources needed to resolve them at runtime. Only useful for
#     those packages which fully generate their configuration during the build. If a
#     component has configuration provided by assembly tooling, that happens after the
#     package is built and this should be set to false to prevent spurious errors.
#     Type: boolean
#     Default: true
#
#   repository (optional)
#     The repository host name part of the package URL. Defaults to "fuchsia.com".
#     See https://fuchsia.dev/fuchsia-src/concepts/packages/package_url#repository
#     for more details.
#     Type: string
#     Default: fuchsia.com
#
#   subpackages (optional)
#     A list of `fuchsia_package` targets. Each target is converted into the
#     equivalent of a `renameable_targets` entry with its `package` property set
#     to the target, and no `name` override. All included `package` entries will
#     be added as `deps` of the generated meta file, and do not need to be
#     listed as additional `deps` of the `fuchsia_package` target.
#     Subpackage names must be unique (relative to the containing package), but
#     both `renameable_subpackages` and `subpackages` may be included,
#     additively.
#     Type: list of targets
#
#   renameable_subpackages (optional)
#     A list of subpackages defined by scoped variables `package` and an
#     optional `name`. If `name` is omitted, the subpackage target's package
#     name is used by default. The generated package will include a
#     `subpackages` meta file that declares dependencies on the listed packages,
#     using the current package hash of each package. All included `package`
#     entries will be added as `deps` of the generated meta file, and do not
#     need to be listed as additional `deps` of the `fuchsia_package` target.
#     Subpackage names must be unique (relative to the containing package), but
#     both `renameable_subpackages` and `subpackages` may be included,
#     additively.
#     Type: list of scopes
#
#   shell_commands (optional)
#     An explicit list of dependencies included as part of the fuchsia package invocation that are
#     shell command dependencies to include in the shell command distribution manifest and it's
#     subsequent metadata walk
#
#   is_shell_package (optional)
#     Used internally to implement fuchsia_shell_package(). Use with caution, as this flag marks
#     all the package's binaries as shell commands and includes them in the shell_commands package
#     during the generation of the legacy_assembly_input_bundle
#
#   data_deps
#   deps
#   testonly
#   visibility
template("fuchsia_package_with_single_component") {
  package_name = target_name
  if (defined(invoker.package_name)) {
    package_name = invoker.package_name
  }
  component_name = package_name
  if (defined(invoker.component_name)) {
    component_name = invoker.component_name
  }

  component_target = "${target_name}_component"
  fuchsia_component(component_target) {
    forward_variables_from(invoker,
                           [
                             "applicable_licenses",
                             "deps",
                             "data_deps",
                             "manifest",
                             "manifest_deps",
                             "restricted_features",
                             "check_includes",
                             "check_references",
                             "experimental_force_runner",
                             "cm_label",
                             "testonly",
                           ])
    if (!defined(deps)) {
      deps = []
    }

    if (defined(invoker.shell_commands)) {
      deps += invoker.shell_commands
    }

    component_name = component_name
    visibility = [ ":*" ]
  }

  fuchsia_package(target_name) {
    forward_variables_from(invoker,
                           [
                             "applicable_licenses",
                             "is_shell_package",
                             "shell_commands",
                             "disable_elf_binaries_checks",
                             "validate_structured_config",
                             "repository",
                             "renameable_subpackages",
                             "subpackages",
                             "testonly",
                             "visibility",
                           ])
    package_name = package_name
    deps = [ ":$component_target" ]
  }
}