# 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("//build/dist/fini_manifest.gni")
import("//build/images/args.gni")
import("//build/packages/package_metadata.gni")
import("//src/sys/pkg/bin/pm/pm.gni")
import("//tools/cmc/build/validate_component_manifest_references.gni")

# Defines a Fuchsia package.
# See: https://fuchsia.dev/fuchsia-src/development/components/build
#
# Fuchsia packages are a collection of any number of files (or resources), each
# with a unique path that is relative to the package's root.
# Package targets collect resources via their dependencies. These dependencies
# are typically fuchsia_component() targets, which provide their component
# manifest and other files that the component needs (such as an executable).
#
# Packages can be defined as a collection of pairs each representing a file in
# the package. Each pair consists of the path in the package that is assigned
# to the file, and a path relative to the build system's output directory where
# the contents of the file will be sourced from.
# This mapping is generated at build time, and is known as the package
# manifest.
#
# To view the package manifest, For instance assume you have defined
# a package at `path/to/project:my_package` and built it:
# ```
# $ fx build path/to/project:my_package
# ```
# You can then find the path to the generated manifest:
# ```
# $ fx gn outputs out/default path/to/project:my_package_manifest
# ```
#
# The package name is defined by the target name.
# Some rules apply to package names.
# See: https://fuchsia.dev/fuchsia-src/concepts/packages/package_url#package-name
#
# It's recommended for a package to depend on one or more `fuchsia_component()`
# targets. Typically no other dependencies are required.
#
# Example:
# ```
# fuchsia_package("my-package") {
#   deps = [
#     ":first_component",
#     ":second_component",
#   ]
# }
# ```
#
# Parameters
#
#   package_name (optional)
#     The name of the package.
#     Type: string
#     Default: target_name
#
#   deps
#   testonly
#   visibility
template("fuchsia_package") {
  package_name = target_name
  if (defined(invoker.package_name)) {
    package_name = invoker.package_name
  }

  # Generate the "meta/package" file
  meta_package_target = "${target_name}_meta_package"
  generate_meta_package(meta_package_target) {
    forward_variables_from(invoker, [ "testonly" ])
    visibility = [ ":*" ]
    package_name = package_name
  }

  # Generate package manifest
  package_manifest_target = "${target_name}_manifest"
  package_manifest_file = "$target_out_dir/${target_name}_manifest"
  fini_manifest(package_manifest_target) {
    forward_variables_from(invoker,
                           [
                             "deps",
                             "testonly",
                           ])
    if (!defined(deps)) {
      deps = []
    }
    deps += [ ":$meta_package_target" ]
    visibility = [ ":*" ]
    outputs = [ package_manifest_file ]
  }

  # Build package
  pm_build(target_name) {
    forward_variables_from(invoker,
                           [
                             "deps",
                             "testonly",
                             "visibility",
                           ])
    manifest = ":$package_manifest_target"
    metadata = {
      if (defined(invoker.metadata)) {
        forward_variables_from(invoker.metadata, "*")
      }
      if (!bootfs_only) {
        # If the bringup configuration is being built, the contents need to be
        # exposed to other containers.
        # See fxbug.dev/45680 for more information.
        distribution_entries_barrier = []
      }
    }
  }
}